> ## Documentation Index > Fetch the complete documentation index at: https://docs.extat.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a transfer between two bank accounts of the same company. > Creates a new account transfer, debiting the origin account and crediting the destination account atomically. Send idempotency_key on every request to make retries safe: replaying the same key (even after the transfer was reversed) returns the existing transfer with 200 instead of moving money again. Returns 201 for a newly created transfer and 200 for an idempotent replay — in both cases the body includes the two resulting account balances. ## OpenAPI ````yaml /openapi/extat-openapi.json post /companies/transfers openapi: 3.0.0 info: contact: email: contato@cernedigital.io name: Cerne Digital url: https://cernedigital.io description: >- API REST da Extat Plataforma usada pelo painel web. Artefato OpenAPI 3.0 para a documentação Mintlify (tags em PT-BR). license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://swagger.io/terms/ title: Extat Plataforma - API REST version: '1.0' servers: - url: https://golang-api-vgnqx.ondigitalocean.app/v1 security: [] tags: - name: Autenticação - name: Bancos - name: Contas Bancárias - name: Plano e Assinaturas - name: Empresa - name: Centros de Custo - name: Painel - name: Demonstrativos - name: Saúde - name: Convites - name: Membros - name: Onboarding - name: Fornecedores - name: Usuário paths: /companies/transfers: post: tags: - Empresa summary: Create a transfer between two bank accounts of the same company. description: >- Creates a new account transfer, debiting the origin account and crediting the destination account atomically. Send idempotency_key on every request to make retries safe: replaying the same key (even after the transfer was reversed) returns the existing transfer with 200 instead of moving money again. Returns 201 for a newly created transfer and 200 for an idempotent replay — in both cases the body includes the two resulting account balances. parameters: - description: company uuid in: header name: x-company-id required: true schema: type: string requestBody: content: application/json: schema: $ref: >- #/components/schemas/account_transfer.CreateAccountTransferRequestDTO description: Transfer data required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/account_transfer.AccountTransferResponseDTO description: >- idempotent replay (same idempotency_key); reversed_at may be filled if the original transfer was already reversed '201': content: application/json: schema: $ref: >- #/components/schemas/account_transfer.AccountTransferResponseDTO description: transfer created '400': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: >- malformed body, invalid x-company-id/account id, idempotency_key over 64 chars, same origin/destination account, amount <= 0, or transfer_date in the future '403': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: >- origin or destination account does not belong to the informed company '404': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: origin or destination account not found '409': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: idempotency_key already used with a different payload '422': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: origin or destination account is inactive '500': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponseDTO' description: Internal Server Error security: - ApiKeyAuth: [] components: schemas: account_transfer.CreateAccountTransferRequestDTO: properties: amount: description: >- Amount NÃO carrega `validate:"required"`: para go-playground/validator, "required" num float64 rejeita o ZERO VALUE — e amount=0 é exatamente o caso de negócio que precisa produzir "valor da transferência deve ser maior que zero" (400, mensagem literal da tabela do plan.md), não o genérico "erro ao validar a requisição". Deixar o campo passar por esta validação de forma e cair na validação de NEGÓCIO do use case (T7, toRegisterParams) é o que garante a mensagem certa em amount<=0. type: number destination_bank_account_id: type: string idempotency_key: description: >- IdempotencyKey é opcional no schema (plan.md), mas o front DEVE sempre enviá-la — ver spec.md § "Regras de negócio". Aceita nil (campo ausente). type: string more_infos: type: string origin_bank_account_id: type: string reference: type: string transfer_date: type: string required: - destination_bank_account_id - origin_bank_account_id - transfer_date type: object account_transfer.AccountTransferResponseDTO: properties: amount: type: string amount_value: type: number created_at: type: string created_by: type: object destination_account: type: object destination_balance: type: number id: type: string more_infos: type: string origin_account: type: object origin_balance: description: >- OriginBalance/DestinationBalance só vêm preenchidos na resposta de criação (201/200 do POST) e de estorno (DELETE) — plan.md: "a resposta inclui os saldos resultantes das duas contas, para o front atualizar a tela sem refetch". GetByID/GetAll/PATCH não carregam efeito de saldo nenhum, então ficam de fora (omitempty) para não sugerir um refetch de saldo que a operação não fez. type: number reference: type: string reversed_at: description: >- ReversedAt só aparece (ponteiro não-nil) quando a transferência foi estornada (D5b) — inclusive no replay idempotente pós-estorno (T4b): o handler responde 200 e o cliente vê, pelo campo preenchido, que aquela chave já havia sido usada e a transferência desfeita. type: string transfer_date: type: string type: type: string updated_at: type: string type: object handler.ErrorResponseDTO: properties: error: type: string message: type: string type: object securitySchemes: ApiKeyAuth: description: >- Token da sessão no cabeçalho Authorization, no formato Bearer (mesmo esquema ApiKeyAuth do contrato). in: header name: Authorization type: apiKey ````