GUIA DE INTEGRAÇÃO · PRODUÇÃO
API do Foou
Cadastro central, bancos exclusivos por cliente e recebimento de notificações NF-e e NFC-e.
Primeiros passos
- Configure o backend e o administrador conforme o README do repositório.
- Entre no portal, cadastre um cliente e seus CNPJs.
- Provisione o banco com o worker em execução.
- Configure o segredo do webhook do cliente. O token da API continua por CNPJ/filial.
- Envie um payload fictício NF-e ou NFC-e com Bearer. Um 200 confirma apenas a persistência.
https://api.foou.com.br
Datas retornadas em ISO 8601. CNPJs, números e séries são texto. Este contrato não recebe valores monetários estruturados. Listagens são limitadas a 500 registros; não há paginação nesta versão. O webhook deduplica payloads idênticos e preserva mudanças de status como novas notificações, sem atualizar a situação fiscal. Limite do corpo: 256 KiB.
Autenticação e permissões
O portal é restrito a administradores da plataforma com acesso aos clientes cadastrados. Não existe acesso de usuários de clientes nesta versão. Login gera cookie HttpOnly, SameSite=Strict, Secure em produção, válido por 8 horas. Escritas exigem Origin igual à configuração APP_ORIGIN e o cabeçalho X-CSRF-Token retornado pelo login. Não há CORS entre origens nesta versão.
O webhook usa Authorization: Bearer com segredo configurado por cliente; segredos anteriores por filial são aceitos durante a transição. Esse segredo é separado do token de acesso à API Focus. Tokens e chaves nunca são devolvidos. Na edição, campo vazio mantém o valor existente; remoção é explícita. Limites administrativos: 180 requisições/minuto por IP, com login limitado a 10 tentativas/minuto. Ao receber 429, respeite o cabeçalho Retry-After.
Downloads
Gerados do mesmo OpenAPI. Variáveis sensíveis ficam vazias e todas as escritas são puladas pelo Runner por padrão.
openapi.json ↗collection.json ↗environment.json ↗README.txt ↗foou-postman.zip ↗Autenticação
Entrar no portal
/api/admin/loginOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| Origin | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| string | Sim | |
| password | string | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/login" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"email":"admin@example.invalid","password":""}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/login", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"email": "admin@example.invalid",
"password": ""
}),
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"email": "admin@example.invalid",
"password": ""
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"csrf": {
"type": "string"
}
},
"required": []
}
}
}Autenticação
Consultar sessão
/api/admin/sessionOperação administrativa restrita aos administradores da plataforma Foou.
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/session" \ -b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/session", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"csrf": {
"type": "string"
}
},
"required": []
}
}
}Autenticação
Encerrar sessão
/api/admin/logoutOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/logout" \ -b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/logout", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 204 | Concluído sem conteúdo |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{}Administração
Listar clientes
/api/admin/clientsLista até 500 clientes, ordenados por criação. Paginação ainda não implementada.
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients" \ -b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"provisioning",
"active",
"failed"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"status",
"createdAt"
]
}
},
"limit": {
"type": "integer"
}
},
"required": []
}
}
}Administração
Cadastrar cliente
/api/admin/clientsOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| name | string | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/clients" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"name":"Cliente Demonstração"}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"name": "Cliente Demonstração"
}),
});Respostas
| 201 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"name": "Cliente Demonstração"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"provisioning",
"active",
"failed"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"status",
"createdAt"
]
}
}
}Administração
Listar CNPJs
/api/admin/clients/{clientId}/companiesLista até 500 CNPJs do cliente, ordenados pelo nome. Paginação ainda não implementada.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"cnpj": {
"type": "string",
"pattern": "^[0-9]{14}$"
},
"root": {
"type": "string",
"pattern": "^[0-9]{8}$"
}
},
"required": [
"id",
"name",
"cnpj",
"root"
]
}
}
},
"required": []
}
}
}Administração
Cadastrar CNPJ
/api/admin/clients/{clientId}/companiesOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| name | string | Sim |
| cnpj | string | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"name":"Empresa Demonstração","cnpj":"12345678000195"}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"name": "Empresa Demonstração",
"cnpj": "12345678000195"
}),
});Respostas
| 201 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"name": "Empresa Demonstração",
"cnpj": "12345678000195"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"cnpj": {
"type": "string",
"pattern": "^[0-9]{14}$"
},
"root": {
"type": "string",
"pattern": "^[0-9]{8}$"
}
},
"required": [
"id",
"name",
"cnpj",
"root"
]
}
}
}Administração
Solicitar provisionamento
/api/admin/clients/{clientId}/provisionRegistra um job durável. Um worker separado cria banco e usuário exclusivo, aplica o schema e valida a conexão. Chamadas repetidas não duplicam o banco. Falhas podem ser reenfileiradas. Cadastre ao menos um CNPJ antes.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/clients/{clientId}/provision" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/provision", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 202 | Solicitação registrada |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": []
}
}
}Administração
Consultar provisionamento
/api/admin/clients/{clientId}/provisionOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/provision" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/provision", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"pending",
"provisioning",
"active",
"failed"
]
},
"job": {
"type": [
"object",
"null"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"running",
"done",
"failed"
]
},
"attempts": {
"type": "integer"
},
"error_code": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": []
}
}
}Administração
Consultar configuração Focus
/api/admin/clients/{clientId}/companies/{companyId}/integrationOperação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/integration" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/integration", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"tokenConfigured": {
"type": "boolean"
},
"webhookTokenConfigured": {
"type": "boolean"
}
},
"required": [
"tokenConfigured",
"webhookTokenConfigured"
]
}
}
}Administração
Configurar tokens Focus
/api/admin/clients/{clientId}/companies/{companyId}/integrationToken da API por filial. Compatibilidade: webhookToken ainda altera SOMENTE o segredo anterior daquela filial; novos cadastros devem usar PUT /api/admin/clients/{clientId}/webhook. Campos vazios preservam. Nunca retorna segredos.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| token | string | Não |
| webhookToken | string | Não |
cURL
curl -X PUT "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/integration" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"token":"","webhookToken":""}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/integration", {
method: "PUT",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"token": "",
"webhookToken": ""
}),
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"token": "",
"webhookToken": ""
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"tokenConfigured": {
"type": "boolean"
},
"webhookTokenConfigured": {
"type": "boolean"
}
},
"required": [
"tokenConfigured",
"webhookTokenConfigured"
]
}
}
}Administração
Remover token explicitamente
/api/admin/clients/{clientId}/companies/{companyId}/integration/{kind}Operação administrativa restrita aos administradores da plataforma Foou.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
| kind | path | Sim |
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
cURL
curl -X DELETE "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/integration/{kind}" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/integration/{kind}", {
method: "DELETE",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 204 | Concluído sem conteúdo |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{}Integração NFC-e
Receber notificação NFC-e
/webhooks/focus/nfceContrato de recebimento do Foou em produção. Persiste a notificação no banco do cliente antes de responder 200. Payloads idênticos são deduplicados; atualizações de status são preservadas. Retorna 200 em repetição. Não baixa XML, não emite NFC-e, não atualiza situação fiscal e não registra automaticamente o webhook na Focus. Os detalhes de entrega e retentativas do provedor ainda precisam ser confirmados na documentação atual da Focus. Campos adicionais são preservados. Não enviar credenciais no corpo. O CNPJ identifica a filial e seu cliente. Aceita o segredo compartilhado do cliente ou, durante a transição, apenas o segredo anterior daquela filial. Nunca aceita segredo de outro cliente.
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| cnpj_emitente | string | Sim |
| ref | string | Sim |
| status | string | Sim |
| status_sefaz | string | Não |
| mensagem_sefaz | string | Não |
| chave_nfe | string | Não |
| numero | string | Não |
| serie | string | Não |
| caminho_xml_nota_fiscal | string | Não |
| caminho_danfe | string | Não |
| qrcode_url | string | Não |
| url_consulta_nf | string | Não |
| contingencia_offline | boolean | Não |
| contingencia_offline_efetivada | boolean | Não |
cURL
curl -X POST "$BASE_URL/webhooks/focus/nfce" \
-H "Authorization: Bearer $WEBHOOK_TOKEN" \
-H "Content-Type: application/json" \
--data '{"cnpj_emitente":"12345678000195","ref":"nfce-producao-001","status":"autorizado","status_sefaz":"100","mensagem_sefaz":"Autorizado o uso da NF-e","numero":"1","serie":"1","caminho_xml_nota_fiscal":"/arquivos/exemplo/nota-nfce.xml","caminho_danfe":"/arquivos/exemplo/danfe.html"}'JavaScript · servidor
const response = await fetch(process.env.BASE_URL + "/webhooks/focus/nfce", {
method: "POST",
headers: { Authorization: 'Bearer ' + process.env.WEBHOOK_TOKEN, 'Content-Type': 'application/json' },
body: JSON.stringify({
"cnpj_emitente": "12345678000195",
"ref": "nfce-producao-001",
"status": "autorizado",
"status_sefaz": "100",
"mensagem_sefaz": "Autorizado o uso da NF-e",
"numero": "1",
"serie": "1",
"caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfce.xml",
"caminho_danfe": "/arquivos/exemplo/danfe.html"
}),
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 503 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"cnpj_emitente": "12345678000195",
"ref": "nfce-producao-001",
"status": "autorizado",
"status_sefaz": "100",
"mensagem_sefaz": "Autorizado o uso da NF-e",
"numero": "1",
"serie": "1",
"caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfce.xml",
"caminho_danfe": "/arquivos/exemplo/danfe.html"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"recebido": {
"const": true,
"type": "boolean"
}
},
"required": [
"recebido"
]
}
}
}Administração
Listar notificações NFC-e
/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfceConsulta administrativa somente de leitura. Lista até 50 notificações da empresa, da mais recente para a mais antiga. total informa a quantidade persistida. Não retorna payload completo, credenciais ou URLs de documentos. state é o estado de processamento no Foou; status é o valor informado pela Focus. O recebimento não representa importação do XML nem validação fiscal.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfce" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfce", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"received",
"processing",
"processed",
"failed"
]
},
"receivedAt": {
"type": "string",
"format": "date-time"
},
"ref": {
"type": [
"string",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
},
"numero": {
"type": [
"string",
"null"
]
},
"serie": {
"type": [
"string",
"null"
]
},
"statusSefaz": {
"type": [
"string",
"null"
]
},
"hasXml": {
"type": "boolean"
},
"attempts": {
"type": "integer"
},
"lastErrorCode": {
"type": [
"string",
"null"
]
},
"document": {
"type": [
"object",
"null"
],
"properties": {
"amount": {
"type": [
"string",
"null"
]
},
"customer": {
"type": [
"string",
"null"
]
},
"parsed": {
"type": "boolean"
}
}
}
},
"required": [
"id",
"state",
"receivedAt",
"ref",
"status",
"numero",
"serie",
"statusSefaz",
"hasXml"
]
}
},
"total": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"const": 50
}
},
"required": [
"items",
"total",
"limit"
]
}
}
}Integração NF-e
Receber notificação NF-e
/webhooks/focus/nfeContrato de recebimento de NF-e do Foou em produção. Autentica pelo segredo de webhook já configurado para a empresa, separado do token Focus. Persiste a notificação no banco exclusivo do cliente antes de responder 200. Repetições idênticas são deduplicadas em tabela própria de NF-e, separada de NFC-e. Mudanças de status geram novas notificações. Não emite NF-e, não baixa XML nem atualiza a situação fiscal; 200 confirma somente recebimento durável. Configuração e entrega real do evento Focus ainda precisam ser validadas. O CNPJ identifica a filial e seu cliente. Aceita o segredo compartilhado do cliente ou, durante a transição, apenas o segredo anterior daquela filial. Nunca aceita segredo de outro cliente.
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| cnpj_emitente | string | Sim |
| ref | string | Sim |
| status | string | Sim |
| status_sefaz | string | Não |
| mensagem_sefaz | string | Não |
| chave_nfe | string | Não |
| numero | string | Não |
| serie | string | Não |
| caminho_xml_nota_fiscal | string | Não |
| caminho_danfe | string | Não |
| protocolo | string | Não |
cURL
curl -X POST "$BASE_URL/webhooks/focus/nfe" \
-H "Authorization: Bearer $WEBHOOK_TOKEN" \
-H "Content-Type: application/json" \
--data '{"cnpj_emitente":"12345678000195","ref":"nfe-producao-001","status":"autorizado","status_sefaz":"100","mensagem_sefaz":"Autorizado o uso da NF-e","chave_nfe":"NFe00000000000000000000000000000000000000000000","numero":"1","serie":"1","protocolo":"000000000000000","caminho_xml_nota_fiscal":"/arquivos/exemplo/nota-nfe.xml","caminho_danfe":"/arquivos/exemplo/danfe.pdf"}'JavaScript · servidor
const response = await fetch(process.env.BASE_URL + "/webhooks/focus/nfe", {
method: "POST",
headers: { Authorization: 'Bearer ' + process.env.WEBHOOK_TOKEN, 'Content-Type': 'application/json' },
body: JSON.stringify({
"cnpj_emitente": "12345678000195",
"ref": "nfe-producao-001",
"status": "autorizado",
"status_sefaz": "100",
"mensagem_sefaz": "Autorizado o uso da NF-e",
"chave_nfe": "NFe00000000000000000000000000000000000000000000",
"numero": "1",
"serie": "1",
"protocolo": "000000000000000",
"caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfe.xml",
"caminho_danfe": "/arquivos/exemplo/danfe.pdf"
}),
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 503 | Operação indisponível; resposta sem detalhes sensíveis |
Exemplo de payload
{
"cnpj_emitente": "12345678000195",
"ref": "nfe-producao-001",
"status": "autorizado",
"status_sefaz": "100",
"mensagem_sefaz": "Autorizado o uso da NF-e",
"chave_nfe": "NFe00000000000000000000000000000000000000000000",
"numero": "1",
"serie": "1",
"protocolo": "000000000000000",
"caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfe.xml",
"caminho_danfe": "/arquivos/exemplo/danfe.pdf"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"recebido": {
"const": true,
"type": "boolean"
}
},
"required": [
"recebido"
]
}
}
}Administração
Listar notificações NF-e
/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfeConsulta administrativa somente de leitura. Lista até 50 notificações NF-e da empresa, da mais recente para a mais antiga. total informa a quantidade persistida. Não retorna payload completo, credenciais ou URLs de documentos. state é o estado de processamento no Foou; status é o valor informado pela Focus. O recebimento não representa importação do XML nem validação fiscal. Consulta a tabela exclusiva de NF-e, sem misturar registros NFC-e.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfe" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfe", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | JSON ou campos inválidos |
| 401 | Autenticação ausente, inválida ou expirada |
| 403 | Origem/CSRF inválidos ou empresa sem integração |
| 404 | Cliente ou empresa não encontrados |
| 409 | Cadastro duplicado, cliente inativo ou pré-requisito ausente |
| 413 | Payload excede 256 KiB |
| 429 | Limite de requisições atingido |
| 500 | Operação indisponível; resposta sem detalhes sensíveis |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"received",
"processing",
"processed",
"failed"
]
},
"receivedAt": {
"type": "string",
"format": "date-time"
},
"ref": {
"type": [
"string",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
},
"numero": {
"type": [
"string",
"null"
]
},
"serie": {
"type": [
"string",
"null"
]
},
"statusSefaz": {
"type": [
"string",
"null"
]
},
"hasXml": {
"type": "boolean"
},
"attempts": {
"type": "integer"
},
"lastErrorCode": {
"type": [
"string",
"null"
]
},
"document": {
"type": [
"object",
"null"
],
"properties": {
"amount": {
"type": [
"string",
"null"
]
},
"customer": {
"type": [
"string",
"null"
]
},
"parsed": {
"type": "boolean"
}
}
}
},
"required": [
"id",
"state",
"receivedAt",
"ref",
"status",
"numero",
"serie",
"statusSefaz",
"hasXml"
]
}
},
"total": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"const": 50
}
},
"required": [
"items",
"total",
"limit"
]
}
}
}Portal do cliente
Iniciar acesso por certificado
/api/portal/auth/startInicia o fluxo no navegador com e-CNPJ A1 ICP-Brasil. Gera tentativa de 5 minutos e cookie de estado HttpOnly. Retorna authorizeUrl do serviço mTLS dedicado. Se o serviço não estiver configurado, retorna 503; não existe login alternativo sem validação de certificado.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| Origin | header | Sim |
cURL
curl -X POST "$PORTAL_ORIGIN/api/portal/auth/start" \ -b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/auth/start", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"authorizeUrl": {
"type": "string",
"format": "uri"
}
},
"required": [
"authorizeUrl"
]
}
}
}Portal do cliente
Concluir acesso por certificado
/api/portal/auth/callbackCallback automático do navegador após o serviço mTLS validar cadeia, revogação, validade e CNPJ. Exige cookie de estado e código de uso único de 60 segundos. Cria sessão e redireciona para /portal/. Não aceita certificado, CNPJ ou chave privada no corpo.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| code | query | Sim |
| attempt | query | Sim |
cURL
curl -X GET "$PORTAL_ORIGIN/api/portal/auth/callback" \ -b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/auth/callback", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 302 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{}Portal do cliente
Consultar sessão do cliente
/api/portal/sessionOperação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração.
cURL
curl -X GET "$PORTAL_ORIGIN/api/portal/session" \ -b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/session", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"cnpj": {
"type": "string"
},
"csrf": {
"type": "string"
},
"companies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"cnpj": {
"type": "string"
},
"clientId": {
"type": "string",
"format": "uuid"
},
"clientName": {
"type": "string"
}
},
"required": []
}
}
},
"required": [
"cnpj",
"csrf",
"companies"
]
}
}
}Portal do cliente
Encerrar sessão do cliente
/api/portal/logoutOperação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| Origin | header | Sim |
| X-CSRF-Token | header | Sim |
cURL
curl -X POST "$PORTAL_ORIGIN/api/portal/logout" \ -b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/logout", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 204 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{}Portal do cliente
Listar notas fiscais
/api/portal/documentsOperação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. Filtros e paginação são executados no servidor. Datas usam America/Sao_Paulo. Valor e cliente podem estar ausentes enquanto o XML está em processamento. clientId é necessário quando o certificado acessa mais de um cliente.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | query | Não |
| companyId | query | Não |
| from | query | Não |
| to | query | Não |
| search | query | Não |
| number | query | Não |
| series | query | Não |
| status | query | Não |
| model | query | Não |
| min | query | Não |
| max | query | Não |
| page | query | Não |
| size | query | Não |
cURL
curl -X GET "$PORTAL_ORIGIN/api/portal/documents" \ -b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"
JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/documents", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"companyId": {
"type": "string",
"format": "uuid"
},
"model": {
"type": "string",
"enum": [
"55",
"65"
]
},
"ref": {
"type": "string"
},
"accessKey": {
"type": [
"string",
"null"
]
},
"number": {
"type": [
"string",
"null"
]
},
"series": {
"type": [
"string",
"null"
]
},
"issuerCnpj": {
"type": "string"
},
"issuerName": {
"type": [
"string",
"null"
]
},
"customer": {
"type": [
"string",
"null"
]
},
"customerDocument": {
"type": [
"string",
"null"
]
},
"issuedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"status": {
"type": "string"
},
"amount": {
"type": [
"string",
"null"
],
"description": "Valor decimal exato como texto, não centavos inteiros."
},
"parsed": {
"type": "boolean"
},
"hasXml": {
"type": "boolean"
},
"hasDanfe": {
"type": "boolean"
}
},
"required": []
}
},
"total": {
"type": "integer"
},
"totalValue": {
"type": "string"
},
"page": {
"type": "integer"
},
"size": {
"type": "integer"
}
},
"required": [
"items",
"total",
"totalValue",
"page",
"size"
]
}
}
}Portal do cliente
Baixar XML ou abrir DANFE
/api/portal/documents/{documentId}/{kind}Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. O backend busca o arquivo de origem sem expor token ou URL. XML é baixado; PDF abre inline; HTML é baixado como arquivo. Não há armazenamento permanente de XML/PDF.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| documentId | path | Sim |
| kind | path | Sim |
| clientId | query | Sim |
cURL
curl -X GET "$PORTAL_ORIGIN/api/portal/documents/{documentId}/{kind}" \
-b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/documents/{documentId}/{kind}", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Schema de resposta de sucesso
{
"application/xml": {
"schema": {
"type": "string",
"format": "binary"
}
},
"application/pdf": {
"schema": {
"type": "string",
"format": "binary"
}
},
"text/html": {
"schema": {
"type": "string",
"format": "binary"
}
}
}Portal do cliente
Baixar documentos selecionados em ZIP
/api/portal/downloadsOperação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. Até 25 notas e 50 MiB por lote; o conjunto inteiro é autorizado antes dos downloads. Arquivos originais são incluídos em ZIP, sem consolidação em PDF único. Uma preparação em lote por instância.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| Origin | header | Sim |
| X-CSRF-Token | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| clientId | string | Sim |
| kind | string | Sim |
| ids | array | Sim |
cURL
curl -X POST "$PORTAL_ORIGIN/api/portal/downloads" \
-b cookies.txt -H "Origin: $PORTAL_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"clientId":"00000000-0000-4000-8000-000000000001","kind":"xml","ids":["00000000-0000-4000-8000-000000000002"]}'JavaScript · servidor
const response = await fetch(process.env.PORTAL_ORIGIN + "/api/portal/downloads", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.PORTAL_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"clientId": "00000000-0000-4000-8000-000000000001",
"kind": "xml",
"ids": [
"00000000-0000-4000-8000-000000000002"
]
}),
});Respostas
| 200 | Operação concluída |
|---|---|
| 400 | Parâmetros inválidos |
| 401 | Sessão ausente ou expirada |
| 403 | Origem/CSRF, cadastro ou permissão inválida |
| 404 | Cadastro ou documento não encontrado |
| 409 | Arquivo indisponível |
| 413 | Tamanho excedido; selecionar menos documentos |
| 429 | Limite atingido; tentar novamente |
| 503 | Serviço ou arquivo temporariamente indisponível |
Exemplo de payload
{
"clientId": "00000000-0000-4000-8000-000000000001",
"kind": "xml",
"ids": [
"00000000-0000-4000-8000-000000000002"
]
}Schema de resposta de sucesso
{
"application/zip": {
"schema": {
"type": "string",
"format": "binary"
}
}
}Administração
Editar empresa
/api/admin/clients/{clientId}/companies/{companyId}undefined
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| name | string | Sim |
cURL
curl -X PUT "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}", {
method: "PUT",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Cadastro atualizado |
|---|---|
| 403 | Acesso negado |
| 404 | Empresa não encontrada |
Schema de resposta de sucesso
{}Administração
Consultar webhook do cliente
/api/admin/clients/{clientId}/webhookRetorna somente indicadores. legacyCompanyCount conta segredos anteriores preservados para transição sem interromper entregas.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
cURL
curl -X GET "$ADMIN_ORIGIN/api/admin/clients/{clientId}/webhook" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/webhook", {
method: "GET",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Configuração sem segredos |
|---|---|
| 401 | Autenticação obrigatória |
| 403 | Origem/CSRF inválidos |
| 409 | Banco do cliente ainda não está ativo |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"required": [
"webhookTokenConfigured",
"legacyCompanyCount"
],
"properties": {
"webhookTokenConfigured": {
"type": "boolean"
},
"legacyCompanyCount": {
"type": "integer",
"minimum": 0
}
}
}
}
}Administração
Configurar webhook do cliente
/api/admin/clients/{clientId}/webhookSegredo compartilhado pelas filiais do cliente, criptografado exclusivamente em seu banco com AAD do cliente. Preserva os segredos antigos por filial até revogação explícita.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| webhookToken | string | Não |
cURL
curl -X PUT "$ADMIN_ORIGIN/api/admin/clients/{clientId}/webhook" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"webhookToken":"{{webhookToken}}"}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/webhook", {
method: "PUT",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"webhookToken": "{{webhookToken}}"
}),
});Respostas
| 200 | Configuração sem segredos |
|---|---|
| 401 | Autenticação obrigatória |
| 403 | Origem/CSRF inválidos |
| 409 | Banco do cliente ainda não está ativo |
Exemplo de payload
{
"webhookToken": "{{webhookToken}}"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"required": [
"webhookTokenConfigured",
"legacyCompanyCount"
],
"properties": {
"webhookTokenConfigured": {
"type": "boolean"
},
"legacyCompanyCount": {
"type": "integer",
"minimum": 0
}
}
}
}
}Administração
Remover webhook do cliente
/api/admin/clients/{clientId}/webhookRemove explicitamente o segredo do cliente E todos os segredos anteriores das suas filiais. Interrompe recebimento dos webhooks deste cliente. Preserva tokens da API, notas e demais clientes.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
cURL
curl -X DELETE "$ADMIN_ORIGIN/api/admin/clients/{clientId}/webhook" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/webhook", {
method: "DELETE",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 204 | Removido |
|---|---|
| 401 | Autenticação obrigatória |
| 403 | Origem/CSRF inválidos |
| 409 | Banco do cliente ainda não está ativo |
Schema de resposta de sucesso
{}Administração
Revogar segredos anteriores das filiais
/api/admin/clients/{clientId}/webhook/legacyUsar somente depois de atualizar todas as filiais para o segredo do cliente. Revoga apenas segredos antigos por filial; mantém o segredo do cliente e os tokens da API. Requer segredo do cliente configurado.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
cURL
curl -X DELETE "$ADMIN_ORIGIN/api/admin/clients/{clientId}/webhook/legacy" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF"JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/webhook/legacy", {
method: "DELETE",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
});Respostas
| 200 | Transição concluída |
|---|---|
| 403 | Origem/CSRF inválidos |
| 409 | Configure o segredo do cliente antes de revogar os antigos |
Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"required": [
"webhookTokenConfigured",
"legacyCompanyCount"
],
"properties": {
"webhookTokenConfigured": {
"type": "boolean"
},
"legacyCompanyCount": {
"type": "integer",
"minimum": 0
}
}
}
}
}Administração
Criar webhook da empresa
/api/admin/clients/{clientId}/companies/{companyId}/webhooksAção explícita por filial, apenas em produção. Requer token da API da filial e segredo do webhook do cliente salvos. Consulta GET /v2/hooks antes do POST para evitar duplicação, incluindo chamadas simultâneas e repetição após falha incerta. Reutiliza cadastro compatível existente; conflito de configuração retorna409 e não remove/substitui nenhum webhook. Não cria ao salvar token/segredo. Retorna apenas metadados públicos, nunca credenciais. NFC-e autorizada (nfce) está descrita no guia geral mais recente; é distinta de nfce_consulta_automatica.
Parâmetros
| Nome | Local | Obrigatório |
|---|---|---|
| clientId | path | Sim |
| companyId | path | Sim |
| X-CSRF-Token | header | Sim |
| Origin | header | Sim |
Corpo da requisição
| Campo | Tipo | Obrigatório |
|---|---|---|
| event | string | Sim |
cURL
curl -X POST "$ADMIN_ORIGIN/api/admin/clients/{clientId}/companies/{companyId}/webhooks" \
-b cookies.txt -H "Origin: $ADMIN_ORIGIN" -H "X-CSRF-Token: $CSRF" \
-H "Content-Type: application/json" \
--data '{"event":"nfe"}'JavaScript · servidor
const response = await fetch(process.env.ADMIN_ORIGIN + "/api/admin/clients/{clientId}/companies/{companyId}/webhooks", {
method: "POST",
headers: { Cookie: process.env.SESSION_COOKIE, Origin: process.env.ADMIN_ORIGIN, 'X-CSRF-Token': process.env.CSRF, 'Content-Type': 'application/json' },
body: JSON.stringify({
"event": "nfe"
}),
});Respostas
| 200 | Webhook compatível já existe; não criou duplicado |
|---|---|
| 201 | Webhook criado em produção |
| 400 | Dados/evento inválidos |
| 401 | Autenticação administrativa obrigatória |
| 403 | Origem ou CSRF inválidos |
| 404 | Empresa não pertence ao cliente |
| 409 | Cadastre token e segredo, aguarde outra operação ou confira conflito existente |
| 422 | Token recusado, sem permissão ou evento/dados rejeitados pela integração |
| 502 | Operação não confirmada pela integração; próxima tentativa consulta antes de criar |
Exemplo de payload
{
"event": "nfe"
}Schema de resposta de sucesso
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"event": {
"type": "string"
},
"cnpj": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"created": {
"type": "boolean"
},
"environment": {
"const": "producao"
}
}
}
}
}