API atual/Referência completa/Exportação contábil

Contadores e convites

Lista os contadores da loja, convida um novo contador por e-mail e revoga convites pendentes.

Contador é um usuário da loja com um perfil fixo, que só lê, exporta e fecha meses. O dono o cria por convite: o convite vale 7 dias e só pode ser aceito uma vez.

Listar contadores

Devolve os usuários que já aceitaram o convite e os convites ainda registrados (qualquer estado). Útil para a tela de equipe contábil.

GET/api/v1/admin/accounting/accountantsAdmin

Lista contadores e convites

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/accountants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contadores e convites

json

{
  "accountants": [
    {
      "id": "bfdf2678-298e-4c18-84fc-fadaf5355fee",
      "email": "contador@escritorio.example.com",
      "last_login_at": "2026-10-02T22:25:26Z"
    }
  ],
  "invites": [
    {
      "id": "5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11",
      "email": "contador@escritorio.example.com",
      "status": "pending",
      "expires_at": "2026-10-18T14:02:11Z",
      "created_at": "2026-10-11T14:02:11Z"
    }
  ]
}

Campos da resposta

accountantsarray

Usuários vinculados a um grupo que concede view_accounting. Atenção: inclui qualquer usuário com esse privilégio, não só os criados por convite.

accountants[].iduuid

Id do usuário.

accountants[].emailstring

E-mail do usuário.

accountants[].last_login_atstring|null

Último login (RFC 3339), ou null se nunca entrou.

invitesarray

Convites do tenant, de qualquer estado.

invites[].iduuid

Id do convite, usado para revogar.

invites[].emailstring

E-mail convidado, em minúsculas.

invites[].statusstring

pendingacceptedexpiredrevoked

pending, accepted, expired ou revoked.

invites[].expires_atstring

Validade (RFC 3339, 7 dias após a criação).

invites[].created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `view_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"view_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Convidar um contador

Cria um convite de uso único para o e-mail informado. O e-mail é normalizado (espaços cortados, minúsculas) e precisa conter @.

POST/api/v1/admin/accounting/accountants/invitesAdmin

Convida um contador

Corpo da requisição

emailstringobrigatório

E-mail do contador.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/accountants/invites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contador@escritorio.example.com"
  }'

Resposta

201Convite criado

json

{
  "id": "5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11",
  "email": "contador@escritorio.example.com",
  "status": "pending",
  "expires_at": "2026-10-18T14:02:11Z",
  "created_at": "2026-10-11T14:02:11Z"
}

Campos da resposta

iduuid

Id do convite.

statusstring

Sempre pending na criação.

expires_atstring

Validade, 7 dias à frente.

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido, e-mail vazio ou sem `@`.	`{"error":"invite_failed","detail":"invalid email"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Revogar um convite

Marca como revoked um convite que ainda não foi aceito. O link deixa de funcionar.

DELETE/api/v1/admin/accounting/accountants/invites/{id}Admin

Revoga um convite

Parâmetros de caminho

iduuidobrigatório

Id do convite (campo id da lista).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/accounting/accountants/invites/5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Convite revogado

json

{
  "ok": true
}

Erros

Status	Quando	Corpo de exemplo
400	Convite inexistente ou que não está `pending`.	`{"error":"revoke_failed","detail":"invite not found or not pending"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Veja também

Exportação contábil

API atual/Referência completa/Exportação contábil

Contadores e convites

Lista os contadores da loja, convida um novo contador por e-mail e revoga convites pendentes.

Contador é um usuário da loja com um perfil fixo, que só lê, exporta e fecha meses. O dono o cria por convite: o convite vale 7 dias e só pode ser aceito uma vez.

Listar contadores

Devolve os usuários que já aceitaram o convite e os convites ainda registrados (qualquer estado). Útil para a tela de equipe contábil.

GET/api/v1/admin/accounting/accountantsAdmin

Lista contadores e convites

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/accountants" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contadores e convites

json

{
  "accountants": [
    {
      "id": "bfdf2678-298e-4c18-84fc-fadaf5355fee",
      "email": "contador@escritorio.example.com",
      "last_login_at": "2026-10-02T22:25:26Z"
    }
  ],
  "invites": [
    {
      "id": "5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11",
      "email": "contador@escritorio.example.com",
      "status": "pending",
      "expires_at": "2026-10-18T14:02:11Z",
      "created_at": "2026-10-11T14:02:11Z"
    }
  ]
}

Campos da resposta

accountantsarray

Usuários vinculados a um grupo que concede view_accounting. Atenção: inclui qualquer usuário com esse privilégio, não só os criados por convite.

accountants[].iduuid

Id do usuário.

accountants[].emailstring

E-mail do usuário.

accountants[].last_login_atstring|null

Último login (RFC 3339), ou null se nunca entrou.

invitesarray

Convites do tenant, de qualquer estado.

invites[].iduuid

Id do convite, usado para revogar.

invites[].emailstring

E-mail convidado, em minúsculas.

invites[].statusstring

pendingacceptedexpiredrevoked

pending, accepted, expired ou revoked.

invites[].expires_atstring

Validade (RFC 3339, 7 dias após a criação).

invites[].created_atstring

Criação (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `view_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"view_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Convidar um contador

Cria um convite de uso único para o e-mail informado. O e-mail é normalizado (espaços cortados, minúsculas) e precisa conter @.

POST/api/v1/admin/accounting/accountants/invitesAdmin

Convida um contador

Corpo da requisição

emailstringobrigatório

E-mail do contador.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/accountants/invites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contador@escritorio.example.com"
  }'

Resposta

201Convite criado

json

{
  "id": "5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11",
  "email": "contador@escritorio.example.com",
  "status": "pending",
  "expires_at": "2026-10-18T14:02:11Z",
  "created_at": "2026-10-11T14:02:11Z"
}

Campos da resposta

iduuid

Id do convite.

statusstring

Sempre pending na criação.

expires_atstring

Validade, 7 dias à frente.

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido, e-mail vazio ou sem `@`.	`{"error":"invite_failed","detail":"invalid email"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Revogar um convite

Marca como revoked um convite que ainda não foi aceito. O link deixa de funcionar.

DELETE/api/v1/admin/accounting/accountants/invites/{id}Admin

Revoga um convite

Parâmetros de caminho

iduuidobrigatório

Id do convite (campo id da lista).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/accounting/accountants/invites/5b0c2f0e-6a52-4d6c-9d1e-2f6a8f0d7c11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Convite revogado

json

{
  "ok": true
}

Erros

Status	Quando	Corpo de exemplo
400	Convite inexistente ou que não está `pending`.	`{"error":"revoke_failed","detail":"invite not found or not pending"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Veja também

Exportação contábil