> 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/construir/api-http/post-trigger-workload-versao-funcao-id.md).

# POST /trigger/{workload}/{versao}/{funcao}/{id}

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

## Rota

```http
POST {SKAIL_BASE_URL}/trigger/{workload}/{versao}/{funcao}/{id}
Content-Type: application/json
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 marcado com `[SkailFunction]` (ou o `skailMethodName`, se definido) | `EmitirFatura`                         |
| `id`       | Identificador da execução (TaskId). Escolhido por quem chama                       | `8f2c3a10-0000-4000-8000-000000000001` |

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 ("Target method not found" no runtime).

O `id` identifica a execução no Monitor e nos logs (`SkailContext.Current.TaskId`). Use um id de negócio estável (o id da fatura, do pedido) quando houver um: facilita achar a execução depois.

## Corpo

Um array JSON com os argumentos da função, na ordem da assinatura, serializados como `System.Text.Json` serializa cada tipo. Função sem parâmetros recebe `[]`.

| Assinatura                                      | Corpo                                      |
| ----------------------------------------------- | ------------------------------------------ |
| `EmitirFatura(Guid faturaId)`                   | `["8f2c3a10-0000-4000-8000-000000000001"]` |
| `ProcessarPedido(Guid pedidoId, decimal valor)` | `["8f2c3a10-...", 149.90]`                 |
| `Iniciar(PedidoDto pedido)`                     | `[{ "id": "...", "itens": [ ... ] }]`      |
| `HelloWorld()`                                  | `[]`                                       |

Argumentos precisam ser serializáveis: primitivos, `Guid`, `DateTime`, records e DTOs, coleções deles. Não passe entidades de ORM nem objetos grandes; passe o id e carregue o resto dentro de um command.

## 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](/construir/api-http/autenticacao-e-headers.md). Os mais comuns: `401`/`403` (chave ou namespace). Se o trigger responde `2xx` mas a execução não aparece no Monitor, ou fica em Na fila, o `nome:versao` do caminho não bate com o `SKAIL_WORKLOAD` de nenhuma aplicação rodando.

## Exemplos

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

```bash
curl -X POST "https://SEU_SKAIL_BASE_URL/trigger/faturamento/v1.0.0/EmitirFatura/8f2c3a10-0000-4000-8000-000000000001" \
  -H "Content-Type: application/json" \
  -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;

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

var faturaId = Guid.NewGuid();
var response = await http.PostAsJsonAsync(
    $"/trigger/faturamento/v1.0.0/EmitirFatura/{faturaId}",
    new object[] { faturaId });

response.EnsureSuccessStatusCode();
```

{% endtab %}

{% tab title="Node.js" %}

```typescript
const url = `${SKAIL_BASE_URL}/trigger/faturamento/v1.0.0/EmitirFatura/${faturaId}`;

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'skail-key': SKAIL_KEY,
    'Skail-namespace': SKAIL_NAMESPACE,
  },
  body: JSON.stringify([faturaId]),
});
if (!res.ok) throw new Error(`trigger falhou: ${res.status}`);
```

{% endtab %}
{% endtabs %}

## Retry no chamador

O trigger é a única etapa que ainda não está sob a durabilidade do skail: se a chamada HTTP 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](/construir/escrever-fluxos/como-disparar-uma-funcao-pela-api-http.md) (guia com o padrão completo em um controller), [POST /api/v1/fire](/construir/api-http/post-api-v1-fire-eventname-instanceid.md), [SkailFunction](/construir/sdk-.net/skailfunction.md) (regras de nome e `skailMethodName`).