FoouDocumentaçãoBaixar Postman ↗

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.

Produção publicada com HTTPS nos domínios Foou. Emissão e importação de XML não estão disponíveis.

Primeiros passos

  1. Configure o backend e o administrador conforme o README do repositório.
  2. Entre no portal, cadastre um cliente e seus CNPJs.
  3. Provisione o banco com o worker em execução.
  4. Configure o segredo do webhook do cliente. O token da API continua por CNPJ/filial.
  5. 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

POST /api/admin/login

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
OriginheaderSim

Corpo da requisição

CampoTipoObrigatório
emailstringSim
passwordstringSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

GET /api/admin/session

Operaçã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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /api/admin/logout

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
X-CSRF-TokenheaderSim
OriginheaderSim

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

204Concluído sem conteúdo
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operação indisponível; resposta sem detalhes sensíveis
Schema de resposta de sucesso
{}

Administração

Listar clientes

GET /api/admin/clients

Lista 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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /api/admin/clients

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
X-CSRF-TokenheaderSim
OriginheaderSim

Corpo da requisição

CampoTipoObrigatório
namestringSim

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

201Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

GET /api/admin/clients/{clientId}/companies

Lista até 500 CNPJs do cliente, ordenados pelo nome. Paginação ainda não implementada.

Parâmetros

NomeLocalObrigatório
clientIdpathSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /api/admin/clients/{clientId}/companies

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
clientIdpathSim
X-CSRF-TokenheaderSim
OriginheaderSim

Corpo da requisição

CampoTipoObrigatório
namestringSim
cnpjstringSim

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

201Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /api/admin/clients/{clientId}/provision

Registra 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

NomeLocalObrigatório
clientIdpathSim
X-CSRF-TokenheaderSim
OriginheaderSim

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

202Solicitação registrada
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

GET /api/admin/clients/{clientId}/provision

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
clientIdpathSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

GET /api/admin/clients/{clientId}/companies/{companyId}/integration

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

PUT /api/admin/clients/{clientId}/companies/{companyId}/integration

Token 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

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim
X-CSRF-TokenheaderSim
OriginheaderSim

Corpo da requisição

CampoTipoObrigatório
tokenstringNão
webhookTokenstringNã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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

DELETE /api/admin/clients/{clientId}/companies/{companyId}/integration/{kind}

Operação administrativa restrita aos administradores da plataforma Foou.

Parâmetros

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim
kindpathSim
X-CSRF-TokenheaderSim
OriginheaderSim

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

204Concluído sem conteúdo
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operação indisponível; resposta sem detalhes sensíveis
Schema de resposta de sucesso
{}

Integração NFC-e

Receber notificação NFC-e

POST /webhooks/focus/nfce

Contrato 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

CampoTipoObrigatório
cnpj_emitentestringSim
refstringSim
statusstringSim
status_sefazstringNão
mensagem_sefazstringNão
chave_nfestringNão
numerostringNão
seriestringNão
caminho_xml_nota_fiscalstringNão
caminho_danfestringNão
qrcode_urlstringNão
url_consulta_nfstringNão
contingencia_offlinebooleanNão
contingencia_offline_efetivadabooleanNã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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
503Operaçã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

GET /api/admin/clients/{clientId}/companies/{companyId}/notifications/nfce

Consulta 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

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /webhooks/focus/nfe

Contrato 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

CampoTipoObrigatório
cnpj_emitentestringSim
refstringSim
statusstringSim
status_sefazstringNão
mensagem_sefazstringNão
chave_nfestringNão
numerostringNão
seriestringNão
caminho_xml_nota_fiscalstringNão
caminho_danfestringNão
protocolostringNã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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
503Operaçã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

GET /api/admin/clients/{clientId}/companies/{companyId}/notifications/nfe

Consulta 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

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim

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

200Operação concluída
400JSON ou campos inválidos
401Autenticação ausente, inválida ou expirada
403Origem/CSRF inválidos ou empresa sem integração
404Cliente ou empresa não encontrados
409Cadastro duplicado, cliente inativo ou pré-requisito ausente
413Payload excede 256 KiB
429Limite de requisições atingido
500Operaçã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

POST /api/portal/auth/start

Inicia 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

NomeLocalObrigatório
OriginheaderSim

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

200Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviç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

GET /api/portal/auth/callback

Callback 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

NomeLocalObrigatório
codequerySim
attemptquerySim

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

302Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviço ou arquivo temporariamente indisponível
Schema de resposta de sucesso
{}

Portal do cliente

Consultar sessão do cliente

GET /api/portal/session

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.

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

200Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviç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

POST /api/portal/logout

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.

Parâmetros

NomeLocalObrigatório
OriginheaderSim
X-CSRF-TokenheaderSim

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

204Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviço ou arquivo temporariamente indisponível
Schema de resposta de sucesso
{}

Portal do cliente

Listar notas fiscais

GET /api/portal/documents

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. 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

NomeLocalObrigatório
clientIdqueryNão
companyIdqueryNão
fromqueryNão
toqueryNão
searchqueryNão
numberqueryNão
seriesqueryNão
statusqueryNão
modelqueryNão
minqueryNão
maxqueryNão
pagequeryNão
sizequeryNã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

200Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviç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

GET /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

NomeLocalObrigatório
documentIdpathSim
kindpathSim
clientIdquerySim

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

200Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviç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

POST /api/portal/downloads

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. 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

NomeLocalObrigatório
OriginheaderSim
X-CSRF-TokenheaderSim

Corpo da requisição

CampoTipoObrigatório
clientIdstringSim
kindstringSim
idsarraySim

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

200Operação concluída
400Parâmetros inválidos
401Sessão ausente ou expirada
403Origem/CSRF, cadastro ou permissão inválida
404Cadastro ou documento não encontrado
409Arquivo indisponível
413Tamanho excedido; selecionar menos documentos
429Limite atingido; tentar novamente
503Serviç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

PUT /api/admin/clients/{clientId}/companies/{companyId}

undefined

Parâmetros

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim

Corpo da requisição

CampoTipoObrigatório
namestringSim

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

200Cadastro atualizado
403Acesso negado
404Empresa não encontrada
Schema de resposta de sucesso
{}

Administração

Consultar webhook do cliente

GET /api/admin/clients/{clientId}/webhook

Retorna somente indicadores. legacyCompanyCount conta segredos anteriores preservados para transição sem interromper entregas.

Parâmetros

NomeLocalObrigatório
clientIdpathSim

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

200Configuração sem segredos
401Autenticação obrigatória
403Origem/CSRF inválidos
409Banco 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

PUT /api/admin/clients/{clientId}/webhook

Segredo 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

NomeLocalObrigatório
clientIdpathSim

Corpo da requisição

CampoTipoObrigatório
webhookTokenstringNã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

200Configuração sem segredos
401Autenticação obrigatória
403Origem/CSRF inválidos
409Banco 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

DELETE /api/admin/clients/{clientId}/webhook

Remove 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

NomeLocalObrigatório
clientIdpathSim

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

204Removido
401Autenticação obrigatória
403Origem/CSRF inválidos
409Banco do cliente ainda não está ativo
Schema de resposta de sucesso
{}

Administração

Revogar segredos anteriores das filiais

DELETE /api/admin/clients/{clientId}/webhook/legacy

Usar 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

NomeLocalObrigatório
clientIdpathSim

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

200Transição concluída
403Origem/CSRF inválidos
409Configure 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

POST /api/admin/clients/{clientId}/companies/{companyId}/webhooks

Açã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

NomeLocalObrigatório
clientIdpathSim
companyIdpathSim
X-CSRF-TokenheaderSim
OriginheaderSim

Corpo da requisição

CampoTipoObrigatório
eventstringSim

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

200Webhook compatível já existe; não criou duplicado
201Webhook criado em produção
400Dados/evento inválidos
401Autenticação administrativa obrigatória
403Origem ou CSRF inválidos
404Empresa não pertence ao cliente
409Cadastre token e segredo, aguarde outra operação ou confira conflito existente
422Token recusado, sem permissão ou evento/dados rejeitados pela integração
502Operaçã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"
        }
      }
    }
  }
}