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

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.

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.

Verify credentials

GET /fiscal-entities/{id}/pass-invoices

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

Update authentication type

Test switching between all three types:

Type	Attributes
`token`	`password` (the API token)
`user_and_pass`	`password` + `username`
`pass_only`	`password` (certificate password)

PATCH /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": {
      "authentication_type": "token",
      "password": "my-api-token-123"
    }
  }
}

Deactivate credentials

PATCH /fiscal-entities/{id}/pass-invoices
{
  "data": {
    "type": "fiscal-entity-pass-invoices",
    "attributes": { "password": "" }
  }
}

Expect 200 with status: "inactive".

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.

Check for existing certificate

GET /fiscal-entities/{id}/certificate

Expect 200 with data: null if no certificate exists.

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.

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.

Verify certificate status

GET /fiscal-entities/{id}/certificate

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

Delete certificate

DELETE /fiscal-entities/{id}/certificate

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

Confirm deletion

GET /fiscal-entities/{id}/certificate

Expect 200 with data: null.

Error Cases

Scenario	Request	Expected
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

Verify credentials exist

GET /fiscal-entities/{id}/pass-invoices

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

Emission Setup

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

Scenario	Request	Expected
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'