> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/referencia/api-http/post-trigger.md).

# POST trigger

Inicia a execução de uma function. É a porta de entrada de todo fluxo durável: a partir daqui, o skail assume a execução.

## Rota

```http
POST {SKAIL_BASE_URL}/api/v1/trigger/{workload}/{versao}/{funcao}/{id}
Content-Type: application/json
Authorization: Bearer SUA_SKAIL_KEY
skail-key: SUA_SKAIL_KEY
Skail-namespace: SEU_NAMESPACE

[ ...argumentos da função, em ordem... ]
```

## Parâmetros do caminho

| Segmento   | O que é                                                                                                                                                                            | Exemplo                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `workload` | Nome do workload, o mesmo que está antes dos dois-pontos em `SKAIL_WORKLOAD`                                                                                                       | `faturamento`                          |
| `versao`   | Versão do workload, o que está depois dos dois-pontos em `SKAIL_WORKLOAD`                                                                                                          | `v1.0.0`                               |
| `funcao`   | Nome do método da function, exatamente como está no código. Se a function tiver endereço explícito (`skailMethodName` em C#, opção `uri` em TypeScript), é o método desse endereço | `EmitirFatura`                         |
| `id`       | Identificador da execução (TaskId). Um GUID gerado por quem chama                                                                                                                  | `3f2b8c1e-9a4d-4e7b-8c21-5d6f0a9b1c42` |

Juntos, `workload`, `versao` e `funcao` formam o endereço que o runtime registrou para o método: `faturamento:v1.0.0/EmitirFatura`. Se qualquer um deles não bater com o que a aplicação publicou, a execução não encontra destino e fica parada em Na fila no Monitor.

O `id` identifica a execução no Monitor e nos logs (é o TaskId da execução, lido do contexto do SDK). Ele precisa ser um GUID; id que não é GUID é recusado com `400 invalid_body`. Quem dispara gera o GUID uma vez, reutiliza o mesmo valor nas novas tentativas desse disparo e guarda a relação entre ele e o id de negócio (por exemplo, numa coluna da fatura ou do pedido), para achar a execução no Monitor depois. Se preferir não guardar essa relação, derive o GUID com UUID v5 a partir do namespace do skail e do id de negócio (por exemplo, `SEU_NAMESPACE:4107`), com um GUID fixo da sua aplicação como base. O mesmo pedido gera sempre o mesmo GUID no mesmo environment, e um GUID diferente em cada environment.

## Corpo

Um array JSON com os argumentos da função, na ordem da assinatura. Em C#, cada argumento é serializado como o `System.Text.Json` serializa o tipo dele; em TypeScript, cada argumento é um valor JSON, e datas trafegam como string ISO-8601. Função sem parâmetros recebe `[]`.

| Function                           | Corpo                                      |
| ---------------------------------- | ------------------------------------------ |
| `EmitirFatura(faturaId)`           | `["8f2c3a10-0000-4000-8000-000000000001"]` |
| `ProcessarPedido(pedidoId, valor)` | `["8f2c3a10-...", 149.90]`                 |
| `Iniciar(pedido)`                  | `[{ "Id": "...", "Itens": [ ... ] }]`      |
| `HelloWorld()`                     | `[]`                                       |

Em argumentos que são objetos, os nomes dos campos precisam ter a mesma caixa das propriedades do tipo que a function recebe: com `Itens` no tipo, o campo `itens` no JSON não preenche a propriedade, que chega nula, e a execução segue sem erro. Em C#, o `PostAsJsonAsync` sem opções manda os nomes em camelCase; passe `JsonSerializerOptions.Default`.

Em C#, um enum nos argumentos vai como número no JSON. Se quem dispara manda texto, use um campo `string` no tipo C#. Ver [Passar dados entre função e commands](/construa/como-fazer/passar-dados-entre-funcao-e-commands.md).

{% hint style="warning" %}
Argumentos precisam ser serializáveis em JSON: primitivos, ids, datas, tipos simples e coleções deles. Não passe entidades de ORM nem objetos grandes; passe o id e carregue o resto dentro de um command.
{% endhint %}

## Resposta

Sucesso: resposta `2xx`. A execução foi aceita e vai rodar assim que a aplicação (o workload publicado com esse `nome:versao`) buscar a execução. Se a aplicação não estiver rodando, a execução fica esperando até ela subir.

Erros: ver [Autenticação e headers](/referencia/api-http/autenticacao.md). Os mais comuns: `400` com `missing_headers` (falta um dos três headers) ou `invalid_body` (o `id` não é GUID, ou o corpo é inválido), e `401`/`403` (chave ou namespace). Se o trigger responde `2xx` e a execução fica em Na fila, o `nome:versao` ou a `funcao` do caminho não batem com o que alguma aplicação rodando publicou. Se ela nem aparece no Monitor, a URL base, a chave e o namespace usados no trigger são de outro environment, diferente do que o Monitor está mostrando.

## Exemplos

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://SEU_SKAIL_BASE_URL/api/v1/trigger/faturamento/v1.0.0/EmitirFatura/SEU_GUID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SUA_SKAIL_KEY" \
  -H "skail-key: SUA_SKAIL_KEY" \
  -H "Skail-namespace: SEU_NAMESPACE" \
  -d '["8f2c3a10-0000-4000-8000-000000000001"]'
```

{% endtab %}

{% tab title="C# (HttpClient)" %}

```csharp
using System.Net.Http.Json;
using System.Text.Json;

var skailBaseUrl = Environment.GetEnvironmentVariable("SKAIL_BASE_URL")!;
var skailKey = Environment.GetEnvironmentVariable("SKAIL_KEY")!;
var skailNamespace = Environment.GetEnvironmentVariable("SKAIL_NAMESPACE")!;

// Configure uma vez, por exemplo via IHttpClientFactory
var http = new HttpClient { BaseAddress = new Uri(skailBaseUrl) };
http.DefaultRequestHeaders.Add("Authorization", $"Bearer {skailKey}");
http.DefaultRequestHeaders.Add("skail-key", skailKey);
http.DefaultRequestHeaders.Add("Skail-namespace", skailNamespace);

var faturaId = Guid.NewGuid();
// execucaoId: gere uma vez, grave com a fatura antes de chamar e reutilize nas novas tentativas
var execucaoId = Guid.NewGuid();
var response = await http.PostAsJsonAsync(
    $"/api/v1/trigger/faturamento/v1.0.0/EmitirFatura/{execucaoId}",
    new object[] { faturaId },
    JsonSerializerOptions.Default);

response.EnsureSuccessStatusCode();
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const skailBaseUrl = process.env.SKAIL_BASE_URL!;
const skailKey = process.env.SKAIL_KEY!;
const skailNamespace = process.env.SKAIL_NAMESPACE!;

const faturaId = crypto.randomUUID();
// execucaoId: gere uma vez, grave com a fatura antes de chamar e reutilize nas novas tentativas
const execucaoId = crypto.randomUUID();
const response = await fetch(
  new URL(`/api/v1/trigger/faturamento/v1.0.0/EmitirFatura/${execucaoId}`, skailBaseUrl),
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${skailKey}`,
      "skail-key": skailKey,
      "Skail-namespace": skailNamespace,
    },
    body: JSON.stringify([faturaId]),
  },
);

if (!response.ok) throw new Error(`trigger falhou: ${response.status}`);
```

{% endtab %}
{% endtabs %}

## Retry no chamador

O trigger e o fire ficam fora da durabilidade do skail. Se a chamada HTTP do trigger falhar (rede, `429`, `5xx`), a execução não começou: faça retry com backoff no código que chama, usando o mesmo `id`. Depois que o trigger é aceito, tudo o que acontece dentro da function é retentado e retomado pelo skail.

## Veja também

[Como disparar uma função pela API HTTP](/construa/como-fazer/disparar-uma-funcao-pela-api.md) (guia com o padrão completo em um controller), [POST /api/v1/fire](/referencia/api-http/post-fire.md), [SkailFunction](/referencia/sdk-csharp/skailfunction.md) (referência do SDK C#: regras de nome e `skailMethodName`).