← HomeFleetPay / API

Record formal programmatic acceptance on debit note

Parameters, data structure and responses from the versioned contract.

POST/notas-debito/{id}/aprovar
aprovarNotaDebitoSandbox Base: https://api.fleetpay.site/v1

Technical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.

Formally confirms debit note acceptance by the authorized technical/financial approver, recording IP/request evidence and firing webhook nota_debito.aprovada. Responds 409 if already accepted/rejected. Requires operacao scope.

Authentication

Required Scope
operacao — Operations
Module
Commercial Agreements & Debit Notes
Target Profiles
Transport Manager · Shipper
Schemes
OAuth2 client_credentials (POST /oauth/token) or API Key via Authorization: Bearer / X-Api-Key
[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]
Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

idpath · stringRequired

Numeric ID or UUID of the debit note.

Constraints
{
  "type": "string"
}

Request Body

Required

Approver identification and formal confirmation.

application/json

accepted_by_namestringRequired
accepted_by_emailstring | nullOptional
accepted_by_documentstring | nullOptional
notesstring | nullOptional

Responses

200 HTTP Response

Operation processed successfully.

application/json

data—Optional
metaobject | nullOptional
additionalPropertiestrue
ambientestringOptional
"homologacao" · "producao"
401 HTTP Response

Missing, invalid or cross-environment credential.

403 HTTP Response

Dashboard scope not enabled or resource outside company scope.

404 HTTP Response

Debit note not found.

409 HTTP Response

Debit note already processed or in invalid state.

Complete Operation Definition
{
  "tags": [
    "Notas de Débito"
  ],
  "operationId": "aprovarNotaDebito",
  "summary": "Registrar aceite formal programático em nota de débito",
  "description": "Confirma formalmente o aceite da nota de débito pelo responsável técnico/financeiro autorizado, registrando evidência de IP/request e disparando webhook `nota_debito.aprovada`. Responde `409` se já aceita/rejeitada. Exige escopo `operacao`.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "ID numérico ou UUID da nota de débito.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "description": "Identificação do aprovador e confirmação formal.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "accepted_by_name"
          ],
          "properties": {
            "accepted_by_name": {
              "type": "string"
            },
            "accepted_by_email": {
              "type": [
                "string",
                "null"
              ]
            },
            "accepted_by_document": {
              "type": [
                "string",
                "null"
              ]
            },
            "notes": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Operação processada com sucesso.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "anyOf": [
                  {
                    "type": "object",
                    "additionalProperties": true
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                ]
              },
              "meta": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": true
              },
              "ambiente": {
                "type": "string",
                "enum": [
                  "homologacao",
                  "producao"
                ]
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Credencial ausente, inválida ou de outro ambiente."
    },
    "403": {
      "description": "Escopo do painel não habilitado ou recurso fora do escopo da company."
    },
    "404": {
      "description": "Nota de débito não encontrada."
    },
    "409": {
      "description": "Nota de débito já processada ou em estado inválido."
    }
  },
  "x-fleetpay-scope": "operacao",
  "x-fleetpay-module": "acordos-notas-debito",
  "x-fleetpay-profiles": [
    "gestor",
    "embarcador"
  ],
  "method": "POST",
  "path": "/notas-debito/{id}/aprovar"
}