Visão geral da API de Antecipação

A API de Antecipação permite que um sistema externo (ERP, folha de pagamento ou backoffice) cadastre beneficiários e sincronize os saldos antecipáveis de uma empresa que utiliza o produto de Antecipação da Woovi.

É uma API REST no estilo OpenPix: autenticação por app_id no cabeçalho Authorization, corpo em JSON, valores monetários em centavos e escopos por funcionalidade.

info

Para utilizar esta API é necessário que a empresa possua a funcionalidade de Antecipação (Pix Out) habilitada. Caso contrário, as requisições retornam 403.

Ambiente e URL base

A API de Antecipação usa os mesmos hosts das demais APIs Woovi:

Ambiente	URL base
Produção	https://api.woovi.com
Sandbox (testes)	https://api.woovi-sandbox.com

Todos os endpoints ficam sob o prefixo /api/v1/anticipation.

Autenticação

A autenticação segue o mesmo modelo das demais APIs Woovi: um App ID enviado no cabeçalho Authorization.

1. Crie uma aplicação em app.woovi.com e copie o app_id.
2. Envie-o no cabeçalho Authorization de toda requisição.
3. A empresa é resolvida a partir do app_id — você nunca informa o companyId.

Authorization: {SEU_APP_ID}
Content-Type: application/json

Além do app_id, a autenticação valida:

• IP allowlist — se a aplicação tiver lista de IPs configurada, o IP de origem precisa estar liberado.
• Escopo — a aplicação precisa possuir o escopo exigido pelo endpoint.
• Funcionalidade — a empresa precisa ter Antecipação (Pix Out) habilitada.

Escopos

Escopo	Permite
ANTICIPATION_BENEFICIARY_POST	Cadastrar, ativar e desativar beneficiários
ANTICIPATION_BALANCE_POST	Sincronizar saldos de beneficiários em lote

Convenções

• Valores monetários são sempre inteiros em centavos (ex.: 10000 = R$ 100,00).
• taxID (chave de pagamento do beneficiário) pode ser CPF ou CNPJ, com ou sem máscara — os dígitos são normalizados no servidor.
• Datas são retornadas como strings ISO 8601.

Endpoints

Método	Endpoint	Escopo
POST	/api/v1/anticipation/beneficiary	ANTICIPATION_BENEFICIARY_POST
POST	/api/v1/anticipation/balance/batch	ANTICIPATION_BALANCE_POST
POST	/api/v1/anticipation/beneficiary/{taxID}/activate	ANTICIPATION_BENEFICIARY_POST
POST	/api/v1/anticipation/beneficiary/{taxID}/deactivate	ANTICIPATION_BENEFICIARY_POST

Consulte a referência completa na página API (tag anticipation).

Erros

Status	Significado
400	Corpo/parâmetros inválidos. Formato: { "error": "mensagem" }
401	app_id inválido ou IP não autorizado. Formato: { "data": null, "errors": [{ "message": "Invalid appID" }] }
403	Escopo ausente ou Antecipação não habilitada para a empresa. Formato: { "error": "mensagem" }
404	Beneficiário não encontrado (nas rotas por taxID).
409	Beneficiário já existe para o CPF/CNPJ (no cadastro).