Atendimento: Obrigações
Endpoints da WebApiAlcance para gerenciar obrigações acessórias dos clientes - os compromissos fiscais e contábeis (declarações, guias, entregas) controlados por cliente, competência e prazo de entrega. Cobrem criação individual, importação em lote com deduplicação, importação de planilha CSV, listagem com filtros e paginação, vínculo de modelo de lembrete, detalhamento por ID, atualização parcial e exclusão.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/obrigacoesA URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/obrigacoes.
Escopos necessários
obrigacoes:read- listagem, opções de filtro e detalhamento por IDobrigacoes:write- criação, importações, atualização, exclusão e vínculo de modelo
Escrita exige permissão adicional
Todas as rotas de escrita (POST, PUT, DELETE) exigem, além do escopo, permissão adicional. Sem ela, a resposta é 403 Forbidden.
O escopo é derivado da rota: o prefixo /obrigacoes vira o recurso obrigacoes, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).
Endpoints
POST /obrigacoes/
Cria uma nova obrigação acessória vinculada a um cliente. O único campo obrigatório é id_cliente; os demais são opcionais.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ObrigacaoCreate): id_cliente (obrigatório) e os demais campos do schema (opcionais).
Request
{
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DCTFWeb Mensal",
"tipo": "Declaração",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15",
"status": "pendente"
}Response 201 Created
{
"status": "success",
"message": "Obrigação criada com sucesso",
"data": {
"id": 87,
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DCTFWeb Mensal",
"tipo": "Declaração",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15",
"ent_multa": false,
"status": "pendente",
"legacy_uuid": null,
"data_hora_criacao": "2026-07-03T09:12:00",
"data_hora_atualizacao": "2026-07-03T09:12:00"
}
}Validações de negócio retornam 422 Unprocessable Entity - inclusive quando o id_cliente informado não existe: a existência do cliente é validada antes do insert (evitando um 500 por violação de FK) e a resposta lista os IDs inexistentes (ex.: "Cliente(s) inexistente(s): [1234].").
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
POST /obrigacoes/import
Importa obrigações em lote com upsert e deduplicação explícita (substitui a RPC import_obrigacoes_bulk). O dedup é feito por acessorias_ent_id (quando houver) ou pela tupla (id_cliente, nome, ent_dt_prazo, competencia). O lote é limitado a 2000 itens por requisição - lotes maiores devem ser paginados pelo cliente.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ObrigacaoImportRequest): objeto com o array obrigacoes, em que cada item é um ObrigacaoImportItem que exige id_cliente.
Request
{
"obrigacoes": [
{
"id_cliente": 1234,
"acessorias_ent_id": "ent-001",
"nome": "DCTFWeb Mensal",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15"
},
{
"id_cliente": 1234,
"acessorias_ent_id": "ent-002",
"nome": "EFD Contribuições",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-10"
}
]
}Response 200 OK
{
"status": "success",
"message": "Import de obrigações concluído com sucesso",
"data": {
"inseridos": 1,
"atualizados": 1
}
}Apenas os campos enviados são gravados: item sem acessorias_ent_id, ent_dt_atraso, ent_guia_lida ou ent_last_dh não apaga esses valores na obrigação existente. Lote vazio retorna 422 Unprocessable Entity ("Lista de obrigações vazia."). A existência de todos os id_cliente do lote é validada antes do upsert: qualquer cliente inexistente aborta o import inteiro com 422 ("Cliente(s) inexistente(s): [...]"), evitando 500 por violação de FK.
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
POST /obrigacoes/importacoes
Importa obrigações de uma planilha CSV (multipart/form-data). Síncrona e idempotente: reimportar o mesmo arquivo só atualiza. Linha inválida não impede as válidas; o relatório lista os erros por linha.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
arquivo | file | form | sim | CSV (.csv) com separador ; ou ,, até 4 MB e 50.000 linhas. |
criar_departamentos | bool | form | não | Default false. true cria os departamentos ausentes. |
Colunas do CSV
| Cabeçalho | Obrigatório | Observações |
|---|---|---|
Obrigação / Tarefa | sim | Nome da obrigação. |
Tipo | sim | Obrigação ou Tarefa. |
CNPJ | sim | Identifica a empresa cadastrada. |
Prazo legal | sim | Data DD/MM/AAAA ou AAAA-MM-DD. |
Status | sim | Situação. |
Departamento | sim | Nome do departamento. |
Prazo Técnico, Data da entrega, Responsável prazo, Responsável entrega, Competência, Protocolo | não | Opcionais. |
Request
multipart/form-data com o arquivo no campo arquivo.
Response 200 OK
{
"status": "success",
"message": "10 inserida(s), 2 atualizada(s), 1 erro(s).",
"data": {
"total_linhas": 13,
"inseridas": 10,
"atualizadas": 2,
"departamentos_criados": ["Fiscal"],
"departamentos_criados_total": 1,
"erros": [{ "linha": 7, "campo": "CNPJ", "motivo": "CNPJ inválido" }],
"erros_total": 1,
"avisos": [],
"avisos_total": 0
}
}erros, avisos e departamentos_criados listam no máximo 200 itens; o total real vem em *_total.
Erros: 413 arquivo acima do limite; 422 cabeçalho obrigatório ausente, encoding inválido, mais de 50.000 linhas ou arquivo binário (nada é gravado); 429 excesso de requisições.
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
GET /obrigacoes/
Lista obrigações com filtros, ordenação e paginação. Cada item traz cliente_nome, departamento_nome e modelo_vinculado. O total do filtro, para paginar, vai no header X-Total-Count. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma obrigação encontrada.".
Parâmetros
| Parâmetro | Tipo | Default | Observações |
|---|---|---|---|
id_cliente | int | - | Filtra por cliente. |
departamento_id | int | - | Filtra por departamento. |
departamento_nome | str | - | Filtra pelo nome do departamento (até 200 caracteres). |
status | str | - | Filtra por status (até 50 caracteres). |
prazo_de | date | - | Prazo de entrega a partir de (inclusive). |
prazo_ate | date | - | Prazo de entrega até (inclusive). |
sem_entrega | bool | false | true traz só as obrigações ainda sem data de entrega. |
multa | bool | - | true: só com multa; false: só sem; ausente: todas. |
busca | str | - | Trecho do nome da obrigação, do cliente ou do departamento (até 120 caracteres). |
sort_by | str | - | prazo, nome, cliente, departamento, status ou entrega. Sem sort_by, a lista vem por id crescente. |
sort_dir | str | desc | asc ou desc. |
limit | int | 100 | 1 a 500. |
offset | int | 0 | Offset de paginação (≥ 0). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Obrigações recuperadas com sucesso",
"data": [
{
"id": 87,
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DCTFWeb Mensal",
"tipo": "Declaração",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15",
"ent_multa": false,
"status": "pendente",
"legacy_uuid": null,
"data_hora_criacao": "2026-07-03T09:12:00",
"data_hora_atualizacao": "2026-07-03T09:12:00",
"cliente_nome": "Padaria Exemplo",
"departamento_nome": "Fiscal",
"modelo_vinculado": { "id": 9, "titulo": "Aviso DCTFWeb" }
}
]
}Escopo: obrigacoes:read
GET /obrigacoes/filtros
Devolve as opções de filtro (status e departamentos distintos, sem nulos nem vazios, ordenadas) das obrigações do período. Alimenta os seletores de GET /obrigacoes/.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
prazo_de | date | query | não | Prazo a partir de (inclusive). |
prazo_ate | date | query | não | Prazo até (inclusive). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Filtros recuperados com sucesso",
"data": {
"status": ["entregue", "pendente"],
"departamentos": ["Contábil", "Fiscal"]
}
}Escopo: obrigacoes:read
GET /obrigacoes/{obrigacao_id}
Detalha uma obrigação pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID interno da obrigação |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Obrigação recuperada com sucesso",
"data": {
"id": 87,
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DCTFWeb Mensal",
"tipo": "Declaração",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15",
"ent_multa": false,
"status": "pendente",
"legacy_uuid": null,
"data_hora_criacao": "2026-07-03T09:12:00",
"data_hora_atualizacao": "2026-07-03T09:12:00",
"cliente_nome": "Padaria Exemplo",
"departamento_nome": "Fiscal",
"modelo_vinculado": null
}
}Escopo: obrigacoes:read
PUT /obrigacoes/{obrigacao_id}
Atualiza uma obrigação existente. O body é um ObrigacaoUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id_cliente e legacy_uuid são omitidos do body para evitar mass-assignment.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação |
Request (ObrigacaoUpdate - todos os campos opcionais)
{
"status": "entregue",
"ent_dt_entrega": "2026-07-12"
}Response 200 OK
{
"status": "success",
"message": "Obrigação atualizada com sucesso",
"data": {
"id": 87,
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DCTFWeb Mensal",
"tipo": "Declaração",
"competencia": "2026-06",
"ent_dt_prazo": "2026-07-15",
"ent_dt_entrega": "2026-07-12",
"ent_multa": false,
"status": "entregue",
"legacy_uuid": null,
"data_hora_criacao": "2026-07-03T09:12:00",
"data_hora_atualizacao": "2026-07-12T14:30:00"
}
}Retorna 404 Not Found quando a obrigação não existe e 422 Unprocessable Entity para demais erros de validação.
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
DELETE /obrigacoes/{obrigacao_id}
Remove uma obrigação pelo ID. Quando não encontrada, retorna 404 Not Found.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Obrigação removida com sucesso",
"data": null
}Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
PUT /obrigacoes/{obrigacao_id}/modelo
Vincula (ou troca) o modelo de lembrete da obrigação. O vínculo vale para todas as obrigações com o mesmo nome e departamento. A obrigação precisa ter nome e departamento.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação |
Request
{
"modelo_id": 9
}modelo_id (int, ≥ 1) é obrigatório; campos extras retornam 422.
Response 200 OK
{
"status": "success",
"message": "Modelo vinculado com sucesso",
"data": {
"id": 31,
"obrigacao_nome": "DCTFWeb Mensal",
"departamento": "Fiscal",
"modelo_id": 9
}
}Erros: 404 obrigação ou modelo inexistente; 422 obrigação sem nome ou departamento.
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
DELETE /obrigacoes/{obrigacao_id}/modelo
Remove o vínculo de modelo da obrigação (e de todas com mesmo nome e departamento). Idempotente: sem vínculo, também retorna sucesso.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Vínculo removido com sucesso",
"data": null
}Erros: 404 obrigação inexistente; 422 obrigação sem nome ou departamento.
Escopo: obrigacoes:write + permissão adicional (sem ela, 403)
Schemas
ObrigacaoCreate
Estende o ObrigacaoBase adicionando id_cliente obrigatório.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | Cliente ao qual a obrigação está vinculada. |
departamento_id | int | null | não | Departamento responsável. |
acessorias_ent_id | str | null | não | ID de origem (integração Acessórias). Máx. 64 caracteres. |
nome | str | null | não | Nome da obrigação. Máx. 255 caracteres. |
tipo | str | null | não | Tipo da obrigação. Máx. 100 caracteres. |
competencia | str | null | não | Competência de referência (ex: 2026-06). Máx. 20 caracteres. |
protocolo | str | null | não | Protocolo de entrega. Máx. 100 caracteres. |
ent_dt_prazo | date | null | não | Prazo legal de entrega. |
ent_dt_prazo_tecnico | date | null | não | Prazo técnico interno. |
ent_dt_atraso | date | null | não | Data a partir da qual passa a constar como em atraso. |
ent_dt_entrega | date | null | não | Data efetiva de entrega. |
ent_multa | bool | não | Indica incidência de multa. Default false. |
status | str | null | não | Situação da obrigação. Máx. 50 caracteres. |
ent_guia_lida | str | null | não | Indicador de leitura da guia. Máx. 100 caracteres. |
ent_last_dh | datetime | null | não | Último processamento/atualização de origem. |
resp_prazo | str | null | não | Responsável pelo prazo. Máx. 200 caracteres. |
resp_entrega | str | null | não | Responsável pela entrega. Máx. 200 caracteres. |
ObrigacaoUpdate
Todos os campos são opcionais; apenas os enviados são atualizados. Não aceita id_cliente nem legacy_uuid.
| Campo | Tipo | Observações |
|---|---|---|
departamento_id | int | null | Departamento responsável. |
acessorias_ent_id | str | null | ID de origem. Máx. 64 caracteres. |
nome | str | null | Nome da obrigação. Máx. 255 caracteres. |
tipo | str | null | Tipo da obrigação. Máx. 100 caracteres. |
competencia | str | null | Competência. Máx. 20 caracteres. |
protocolo | str | null | Protocolo. Máx. 100 caracteres. |
ent_dt_prazo | date | null | Prazo legal. |
ent_dt_prazo_tecnico | date | null | Prazo técnico. |
ent_dt_atraso | date | null | Data de atraso. |
ent_dt_entrega | date | null | Data de entrega. |
ent_multa | bool | null | Incidência de multa. |
status | str | null | Situação. Máx. 50 caracteres. |
ent_guia_lida | str | null | Indicador de leitura da guia. Máx. 100 caracteres. |
ent_last_dh | datetime | null | Último processamento de origem. |
resp_prazo | str | null | Responsável pelo prazo. Máx. 200 caracteres. |
resp_entrega | str | null | Responsável pela entrega. Máx. 200 caracteres. |
ObrigacaoRead
Estende o ObrigacaoBase com os campos de identificação e auditoria.
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador da obrigação. |
id_cliente | int | Cliente vinculado. |
legacy_uuid | str | null | UUID de sistema legado, quando existir. |
data_hora_criacao | datetime | Timestamp de criação. |
data_hora_atualizacao | datetime | Timestamp da última atualização. |
Além destes, retorna todos os campos do ObrigacaoBase (departamento_id, acessorias_ent_id, nome, tipo, competencia, protocolo, ent_dt_prazo, ent_dt_prazo_tecnico, ent_dt_atraso, ent_dt_entrega, ent_multa, status, ent_guia_lida, ent_last_dh, resp_prazo, resp_entrega).
ObrigacaoListItem
ObrigacaoRead acrescido dos campos abaixo, devolvido por GET /obrigacoes/ e GET /obrigacoes/{obrigacao_id}.
| Campo | Tipo | Notas |
|---|---|---|
cliente_nome | str | null | Nome do cliente. |
departamento_nome | str | null | Nome do departamento. |
modelo_vinculado | { id, titulo } | null | Modelo de lembrete vinculado (por nome e departamento), quando houver. |
ObrigacaoImportRequest
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
obrigacoes | List[ObrigacaoImportItem] | não | Lote de itens a importar. Default []. Máximo 2000 itens. |
Cada ObrigacaoImportItem tem os mesmos campos do ObrigacaoBase e exige id_cliente por linha.
ObrigacaoImportResult
| Campo | Tipo | Notas |
|---|---|---|
inseridos | int | Quantidade de obrigações novas inseridas. |
atualizados | int | Quantidade de obrigações existentes atualizadas. |
Notas
- Toda resposta de sucesso segue o envelope
{ status, message, data }. Erros usam{ message }(ou{ detail }no422de validação) com o status HTTP correspondente. - O import em lote (
POST /obrigacoes/import) faz upsert com dedup explícito poracessorias_ent_idou pela tupla(id_cliente, nome, ent_dt_prazo, competencia); campos vazios contam como iguais na comparação.
Limite de lote
O POST /obrigacoes/import aceita no máximo 2000 itens por requisição - limite que protege contra payloads gigantes e o consequente N+1 no upsert. Volumes maiores devem ser paginados pelo cliente.