Manual Flow Testing Guide

How to manually test fiscal entity flows using curl.

Prerequisites

  • A valid Bearer Token (JWT from POST /sessions)
  • A Business ID that owns the fiscal entity
  • A Fiscal Entity ID with a valid CNPJ
  • Base URL: https://api.qa.contabeleza.com.br (QA) or https://api.dev.contabeleza.com.br (Dev)

Authentication

Every request requires these headers:

Authorization: Bearer <jwt_token>
ilm-business: <business_id>
Content-Type: application/vnd.api+json
Accept: application/json, application/vnd.api+json

Set Variables

export BASE="https://api.qa.contabeleza.com.br"
export TOKEN="eyJhbG..."
export BID="5"
export FEID="1"  # fiscal entity ID
Tip: Use the Test Runner for automated execution. This guide covers manual testing with curl for debugging or when you need finer control.

Credentials Setup & Validation

Tests the full lifecycle of pass-invoices authentication and digital certificate management for a fiscal entity.

Phase A: Pass Invoices Authentication

1
Create pass-invoices (pass_only) 
POST /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": {
      "password": "test-pass-only",
      "authentication_type": "pass_only"
    }
  }
}

Expect 201. Extract data.id for later steps.

2
Trigger credential validation 
PATCH /fiscal-entities/{id}/pass-invoices/validate

Expect 200 with validation_status: "validating". Validation is async — the system checks credentials against eNotas in the background.

3
Verify credentials 
GET /fiscal-entities/{id}/pass-invoices

Expect 200. Verify authentication_type and status: "active".

4
Update authentication type

Test switching between all three types:

TypeAttributes
tokenpassword (the API token)
user_and_passpassword + username
pass_onlypassword (certificate password)
PATCH /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": {
      "authentication_type": "token",
      "password": "my-api-token-123"
    }
  }
}
5
Deactivate credentials 
PATCH /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": { "password": "" }
  }
}

Expect 200 with status: "inactive".

6
Reactivate credentials 
PATCH /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": {
      "password": "reactivated-password",
      "authentication_type": "pass_only"
    }
  }
}

Expect 200 with status: "active".

Phase B: Certificate Management

Note: Certificate upload/replace steps require a real PFX file and use multipart/form-data. The automated test runner skips these steps. For manual testing, you need a valid PFX file on disk.
1
Check for existing certificate 
GET /fiscal-entities/{id}/certificate

Expect 200 with data: null if no certificate exists.

2
Upload certificate (manual only) 
POST /fiscal-entities/{id}/certificate
Content-Type: multipart/form-data

password: cert123456
data: <binary PFX file>

Expect 201. The certificate is stored encrypted and associated with the fiscal entity.

3
Validate certificate 
PATCH /fiscal-entities/{id}/certificate/validate

Expect 200 with validation_status: "validating". The system checks the certificate expiry, chain, and CNPJ match asynchronously.

4
Verify certificate status 
GET /fiscal-entities/{id}/certificate

Expect 200. After validation completes, status should be "active".

5
Delete certificate 
DELETE /fiscal-entities/{id}/certificate

Expect 200 with status: "inactive". The certificate is soft-deleted.

6
Confirm deletion 
GET /fiscal-entities/{id}/certificate

Expect 200 with data: null.

Error Cases

ScenarioRequestExpected
Invalid entity ID (non-numeric) GET /fiscal-entities/abc/pass-invoices 400 Bad Request
Invalid entity ID for certificate GET /fiscal-entities/abc/certificate 400 Bad Request
Delete certificate for non-existent entity DELETE /fiscal-entities/999999/certificate 404 Not Found

Quick curl Reference

Create pass-invoices

curl -s -X POST "$BASE/fiscal-entities/$FEID/pass-invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ilm-business: $BID" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "fiscal-entity-pass-invoices",
      "attributes": {
        "password": "test-pass-only",
        "authentication_type": "pass_only"
      }
    }
  }' | jq .

Validate credentials

curl -s -X PATCH "$BASE/fiscal-entities/$FEID/pass-invoices/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ilm-business: $BID" | jq .

Emission Setup & Validation

Validates invoice emission setup for a fiscal entity. This flow requires credentials to exist first (run the Credentials flow or ensure pass-invoices/certificate are configured).

Precondition Check

1
Verify credentials exist 
GET /fiscal-entities/{id}/pass-invoices

Expect 200. If 404, you need to create credentials first (see Credentials tab).

Emission Setup

2
Trigger invoice emission setup 
POST /fiscal-entities/{id}/invoices-emission

Expect 200 on success. May return 500 if INVOICES_READ_ONLY=true in the target environment.

This endpoint:

  • Creates the company in eNotas (if not already synced)
  • Sends the digital certificate or authentication credentials
  • Enables the fiscal entity for invoice emission

Error Cases

ScenarioRequestExpected
Invalid entity ID POST /fiscal-entities/abc/invoices-emission 400 Bad Request
Non-existent entity POST /fiscal-entities/999999/invoices-emission 404 Not Found
No credentials configured POST /fiscal-entities/{id}/invoices-emission Possible 500 or 422 depending on env

Quick curl Reference

Setup invoice emission

curl -s -X POST "$BASE/fiscal-entities/$FEID/invoices-emission" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ilm-business: $BID" | jq .

Check emission readiness

curl -s "$BASE/fiscal-entities/$FEID/pass-invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "ilm-business: $BID" | jq '.data.attributes'