🧩 API de Integração¶
Para um ERP, um script ou qualquer sistema criar e acompanhar tarefas de um workspace sem ninguém digitar nada de novo no Nexus. Issue #66. A referência completa de cada rota está em Referência da API e os exemplos prontos em Receitas.
Em um minuto¶
| Base | https://nexus.aamora.com.br/api/v1 |
| Formato | JSON em UTF-8, nos dois sentidos |
| Autenticação | Authorization: Bearer nxk_... (chave de API do workspace) |
| Especificação | /openapi/v1.json, gerada pelo próprio app |
| Limite | 120 chamadas por minuto por chave |
| Escopo desta versão | workspace, listas e status, membros, tarefas (criar, listar, buscar, atualizar) |
Chaves de API¶
Uma chave pertence a um workspace e só enxerga ele. Quem gera é Owner ou Admin, em Configurações do workspace → Integrações:
- Dê um nome à chave, de preferência o do sistema que vai usá-la ("ERP Protheus", "Script de importação").
- Copie o valor completo (
nxk_seguido de 43 caracteres). Ele aparece uma única vez. O Nexus guarda só o SHA-256; a lista mostra apenas o prefixo (nxk_a1b2c3…), a data de criação e o último uso. - Revogar corta o acesso na hora. Cada workspace pode ter até 20 chaves ativas.
Criação e revogação vão para o log de auditoria, com quem fez e qual chave.
sequenceDiagram
participant ERP
participant API as Nexus /api/v1
participant DB as PostgreSQL
ERP->>API: GET /tasks (Authorization: Bearer nxk_...)
API->>API: SHA-256 da chave
API->>DB: WorkspaceApiKeys WHERE KeyHash = ... AND RevokedAtUtc IS NULL
DB-->>API: workspace da chave
API->>DB: tarefas do workspace
DB-->>API: página
API-->>ERP: 200 { items, page, pageSize, total }
Por baixo, isso é um esquema de autenticação próprio (ApiKey), escrito no padrão
AuthenticationHandler do ASP.NET Core
(ApiKeyAuthenticationHandler.cs).
Só as rotas de /api/v1 pedem esse esquema. O restante do app continua no cookie do Identity, e
a chave nunca serve para abrir uma tela.
Respostas de erro¶
Erros vêm como application/problem+json
(RFC 9457), com status, title e detail. Erros de
validação trazem ainda errors, um objeto com o nome do campo e a lista de mensagens.
| Código | Quando | O que fazer |
|---|---|---|
400 |
Corpo inválido ou regra de negócio violada (errors diz o campo) |
Corrigir e reenviar |
401 |
Sem chave, chave desconhecida ou revogada | Conferir o cabeçalho; gerar outra chave |
403 |
Workspace arquivado | Desarquivar nas configurações |
404 |
Tarefa não existe neste workspace | Conferir id ou código |
409 |
externalReference já usada ou tarefa alterada por outra pessoa durante o PATCH |
Ver Receitas |
429 |
Mais de 120 chamadas no minuto | Esperar e repetir |
Exemplo de 400:
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"title": ["Informe o título."],
"assigneeId": ["O responsável precisa ser membro do workspace. Consulte GET /api/v1/members."]
}
}
Convenções¶
- Datas em ISO 8601. O Nexus devolve sempre em UTC com
Z. Na entrada, uma data sem fuso (2026-11-21) é tratada como UTC, do mesmo jeito que a tela de tarefa faz. - Enums como texto:
typeaceitaTask,Bug,Story,Epic;priorityaceitaLowest,Low,Medium,High,Highest;status.categoryéToDo,InProgressouDone. - Ids são GUIDs. Tarefas também podem ser buscadas pelo código mostrado na tela (
TASK-12). - Nomes de campo em camelCase. Campo desconhecido no corpo é ignorado.
- Atualização parcial: no
PATCH, campo ausente ounullnão muda nada; string vazia ("") limpadescription,assigneeIdouexternalReference.
Primeiros passos¶
- Gere a chave em Configurações → Integrações e guarde-a no sistema que vai chamar a API.
GET /api/v1/listspara descobrir otaskListIdde destino e os ids dos status.GET /api/v1/membersse for atribuir tarefas: pegue oiddo membro.POST /api/v1/taskscomtaskListId,titlee, se o seu sistema puder reenviar,externalReferencecom o id da tarefa lá.- A tarefa aparece na lista do Nexus na hora, com o código
TASK-n, e o responsável recebe a notificação de atribuição.
O passo a passo com código em C#, Python e curl está em Receitas.
O que a API não faz (ainda)¶
- Avisar o seu sistema quando uma tarefa muda (webhook de saída): consulte com
updatedSince. - Comentários, anexos, etiquetas, campos personalizados, sprints e épicos.
- Excluir tarefas.
- Chat, docs e planilhas.
A ordem de chegada dessas coisas segue as issues do projeto. Veja também o servidor MCP (#67), que reaproveita estas mesmas chaves.