REST API v2.5 시스템 운영 중

NFE API 문서

NFE API 문서에 오신 것을 환영합니다. 브라질의 전자 송장(NF-e) 발행, 조회 및 취소를 위한 완전한 API입니다. 자동 세금 계산(ICMS, IPI, PIS/COFINS), XML 생성, SEFAZ 승인 및 관리 시스템과의 통합을 지원합니다.

list_alt

중요한 API 필드

중요 필드 해석

이 섹션에서는 올바른 송장 발행 기능에 필수적인 NFE API의 가장 중요한 필드를 설명합니다.

⚠️ ATTENTION: 이 필드의 올바른 구성은 유효한 송장 발행의 기본입니다. 항상 현행 세금 법률을 참조하십시오.

필드	설명	가능한 값	중요도
`invoice_type`	회사 유형 (법인/개인)	`juridica`, `fisica`	높음 - 세금 체계 정의
`nature_of_operation`	거래 성격 (판매, 반품 등)	Ex: `SALE`, `RETURN`	높음 - CFOP 결정
`transaction_type`	거래 유형 (입력/출력)	`INPUT`, `OUTPUT`	높음 - 세금 흐름 방향
`model`	송장 모델	`nfe`, `nfce`	높음 - 문서 모델
`issuance_type`	발행 유형 (일반, 비상)	`NORMAL`, `CONTINGENCY`	중간 - 발행 모드
`ambiente`	처리 환경	`PRODUCTION`, `HOMOLOGATION`	높음 - 대상 SEFAZ 정의
`cliente`	고객/구매자 유형	`CONSUMER`, `TAXPAYER`	높음 - 세금에 영향
`products.origem`	제품 원산지 (국내/수입)	`0` to `8`	높음 - 과세 결정
`products.indicador_total`	제품이 송장 합계에 포함되는지 여부	`true`, `false`	중간 - 샘플 항목용

💡 TIP: 제품의 경우, origem 필드가 중요합니다: 0-국내산, 1-외국 직수입, 2-국내 시장에서 구매한 외국산 등. 상품 원산지의 전체 표를 참조하십시오.

sync_alt

송장 발행 프로세스 흐름

완전한 NF-e 발행 다이어그램

브라질의 전자 송장 발행의 완전한 흐름, 기업 생성부터 최종 파일 생성까지.

business

1. 기업 등록

브라질의 현지 기업 세무 정보 생성

send

2. 정보 전송

주문 데이터 (사용자, 주소, 제품 세금)

receipt

3. 송장 발행

SEFAZ 승인으로 처리 및 전송

assignment_returned

4. 결과 반환

발행 상태 및 NF-e 데이터

description

5. 파일 생성

송장의 XML 및 PDF

published_with_changes

세무 검증

SEFAZ 검증

check_circle

Success

error

Failure

Initial Setup

Data Processing

Fiscal Issuance

Positive Results

📊 Detailed Flow: The process follows a logical 순서: (1) 기업 구성 → (2) 주문 데이터 수신 → (3) NF-e 처리 및 발행 → (4) 상태 반환 → (5) File generation. The decision point (세무 검증) determines whether the issuance was authorized by SEFAZ.

flash_on

엔드포인트 빠른 참조

모든 NFE API 엔드포인트

사용 가능한 모든 API 엔드포인트의 전체 개요입니다. 이 표를 빠른 참조로 사용하여 문서를 탐색하십시오.

Base URL

https://api.tffiscal.com

경로	HTTP 메서드	기능
business 기업 관리
`/api/company/create`	POST	기업 등록
`/api/company/get_detail`	GET	기업 조회
`/api/company/edit`	POST	기업 수정
`/api/company/get_list`	GET	기업 목록
`/api/company/v2/create`	POST	기업 등록 (간소화)
`/api/company/get_cep_detail`	GET	CEP 조회
`/api/company/get_export_invoice_month_files`	GET	월별 내보내기 파일
category 카테고리/세금 관리
`/api/category/get_list`	GET	세금 카테고리 목록
`/api/category/create`	POST	세금 카테고리 생성
`/api/category/get_detail`	GET	카테고리 상세 조회
`/api/category/edit`	POST	세금 카테고리 수정
`/api/category/delete`	POST	세금 카테고리 삭제
receipt 송장 관리
`/api/invoice/create`	POST	송장 발행
`/api/invoice/get_list`	GET	송장 목록
`/api/invoice/get_detail`	GET	송장 상세 조회
`/api/invoice/refresh`	POST	송장 상태 업데이트
`/api/invoice/cancel`	POST	송장 취소
`/api/invoice/invalid`	POST	송장 번호 무효화
`/api/invoice/return`	POST	송장 반환
`/api/invoice/get_xml`	POST	송장 XML 내보내기
receipt NFC-e (소비자 전자 영수증)
`/api/nfce/company/create`	POST	NFC-e 기업 등록
`/api/nfce/company/update`	POST	NFC-e 기업 수정
`/api/nfce/company/get`	POST	NFC-e 기업 조회
`/api/nfce/create`	POST	NFC-e 발행
`/api/nfce/cancel`	POST	NFC-e 취소
`/api/nfce/get_detail`	POST	NFC-e 조회
`/api/nfce/get_danfe`	POST	NFC-e DANFE 받기
`/api/nfce/get_list`	GET	NFC-e 목록(페이지네이션)
description NFS-e (서비스 전자 청구서)
`/api/nfse/create`	POST	NFS-e 발행
`/api/nfse/cancel`	POST	NFS-e 취소
`/api/nfse/get_danfse`	POST	DANFSE 받기 (PDF)
`/api/nfse/get_xml`	POST	NFS-e XML 다운로드
`/api/nfse/get_list`	GET	NFS-e 목록(페이지네이션)
`/api/nfs/company/create`	POST	NFS-e 발행용 기업 등록
receipt_long NF-e — 이벤트 및 조회
`/api/invoice/get_danfe`	POST	NF-e의 DANFE(PDF) 받기
`/api/invoice/consultar_status`	POST	SEFAZ에서 NF-e/NFC-e 상태 조회
`/api/invoice/validar_cpf_cnpj`	POST	연방국세청 데이터베이스에서 CPF/CNPJ 검증
`/api/invoice/cce/send`	POST	정정서(CC-e) 전송
`/api/invoice/cce/get_list`	POST	NF-e의 CC-e 목록 조회
`/api/invoice/cce/download_pdf`	POST	CC-e의 PDF 다운로드
`/api/invoice/cce/download_xml`	POST	CC-e의 XML 다운로드
mark_email_read NF-e — 수취 확인 및 수신 문서
`/api/invoice/manifest`	POST	수취인 수취 확인 이벤트 전송
`/api/invoice/manifest/list`	POST	전송된 수취 확인 목록 조회
`/api/invoice/manifest/get_xml`	POST	수취 확인의 XML 받기
`/api/invoice/received/sync`	POST	수신된 NF-e/이벤트 동기화(DistDFe)
`/api/invoice/received/list`	POST	수신 문서 목록 조회
`/api/invoice/received/get_xml`	POST	수신 문서의 XML 받기
`/api/invoice/received/get_sync_status`	POST	DistDFe 동기화 상태 조회
category NFC-e — 세무 카테고리
`/api/nfce/category/create`	POST	NFC-e 세무 카테고리 생성
`/api/nfce/category/edit`	POST	NFC-e 세무 카테고리 편집
`/api/nfce/category/delete`	POST	NFC-e 세무 카테고리 삭제
`/api/nfce/category/get_detail`	GET	NFC-e 카테고리 상세 정보 받기
`/api/nfce/category/get_list`	GET	NFC-e 세무 카테고리 목록 조회
local_shipping MDF-e (전자 세무 문서 매니페스트)
`/api/mdfe/create`	POST	MDF-e 발행
`/api/mdfe/consult`	POST	MDF-e 상태 조회
`/api/mdfe/cancel`	POST	MDF-e 취소
`/api/mdfe/close`	POST	MDF-e 종료
`/api/mdfe/get_list`	GET	MDF-e 목록(페이지네이션)
inventory_2 DC-e (전자 내용물 신고서)
`/api/dce/create`	POST	DC-e 발행
`/api/dce/consult`	POST	DC-e 상태 조회
`/api/dce/cancel`	POST	DC-e 취소
`/api/dce/pdf`	POST	DC-e의 DACE(PDF) 받기
`/api/dce/get_list`	GET	DC-e 목록(페이지네이션)
local_shipping CT-e (전자 운송장)
`/api/cte/create`	POST	CT-e 발행
`/api/cte/cancel`	POST	CT-e 취소
`/api/cte/cce`	POST	정정서(CC-e)
`/api/cte/desacordo`	POST	용역 불일치 신고
`/api/cte/consult`	POST	CT-e 상태 조회
`/api/cte/inutilize`	POST	번호 범위 무효화
`/api/cte/get_list`	GET	CT-e 목록(페이지네이션)
vpn_key SSO (자동 로그인)
`/api/sso/create_ticket`	POST	자동 로그인 링크 생성
`/api/sso/consume_ticket`	POST	티켓을 소비하고 세션 JWT 수신
account_balance 회계사 관리
`/api/accountant/get_info`	POST	기업에 연결된 회계사 정보 받기

📋 중요 사항:

모든 엔드포인트는 헤더를 통한 인증이 필요합니다: sign, timestamp, token
기업 등록 및 기업 목록 조회에는 배포자 토큰(b2b_token)을 사용하십시오
Content-Type은 항상 다음이어야 합니다 application/json;charset=utf-8
응답은 JSON 표준을 따르며 필드 success, message and data

200

성공

요청이 성공적으로 처리되었습니다

400

클라이언트 오류

잘못되거나 누락된 데이터

500

서버 오류

내부 서버 오류

account_balance

NFE API

브라질 전자 송장 (NF-e)

브라질의 전자 송장(NF-e) 발행, 조회 및 취소를 위한 완전한 API입니다. 자동 세금 계산(ICMS, IPI, PIS/COFINS), XML 생성, SEFAZ 승인 및 관리 시스템과의 통합을 지원합니다. 현재 브라질 전역에서 제품 송장 발행을 지원합니다.

Base URL (운영 환경)

https://api.tffiscal.com/v1

인증

Headers: sign, timestamp, token

요구사항

유효한 A1 디지털 인증서

sync_alt System Flow

input Input Data

Customer Information
Product Data
Fiscal Information
Transport Data

settings Processing

Data validation
Tax calculation
XML generation
SEFAZ authorization

download Output

Invoice XML
Invoice PDF
DANFE (보조 문서)
Authorization status

주요 엔드포인트

POST /api/company/create

새 발행 회사 등록

디스트리뷰터(b2b) 계정에 연결된 발행 회사를 등록합니다. 회사 데이터가 이미 있는 경우 이 엔드포인트를 사용하세요. 디지털 인증서에서 자동 추출하려면 /api/company/v2/create를 사용하세요.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
식별
cnpj *	string	발행 회사 CNPJ
name *	string	회사명
ie *	string	주(州) 등록 번호(Inscrição Estadual)
invoice_type *	string	세제(예: `"simples_nacional"`, `"normal"`)
unit *	string	단위 유형
email	string	회사 이메일
주소
cep *	string	우편번호
address *	string	도로명 주소
house_number *	string	주소 번호
town *	string	지구
city *	string	도시
state *	string	UF(주 약어)
디지털 인증서
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
번호 및 설정
serie *	int	NF-e 시리즈
number *	int	번호 초기값
운송 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 시리즈
number_mdfe	int	MDF-e 시작 번호(번호 매기기 시작점)
serie_cte	int	CT-e 시리즈
number_cte	int	CT-e 시작 번호(번호 매기기 시작점)
serie_dce	int	DC-e 시리즈
number_dce	int	DC-e 시작 번호(번호 매기기 시작점)
is_create_category_template	boolean	기본 세무 카테고리 자동 생성. 기본값: `true`

* 필수 필드.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contato@empresa.com",
          "cep": "01001000",
          "address": "Rua Exemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 1
        }

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

인증서로 자동 입력하여 회사 등록

/api/company/create의 간소화 버전: API가 디지털 인증서를 검증하고 회사명, IE, 주소 등의 데이터를 내부 조회로 자동 추출합니다. cnpj, cert_file, cert_pwd만 필수입니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cnpj *	string	발행 회사 CNPJ
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
is_create_category_template	boolean	기본 세무 카테고리 자동 생성. 기본값: `true`

* 필수 필드.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado"
        }

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/edit

회사 데이터 편집

발행 회사 데이터를 업데이트합니다. 변경하려는 필드만 보내세요 — company_id를 제외한 모든 필드는 선택 사항입니다. CNPJ는 변경할 수 없습니다: 보내면 오류를 반환합니다. cep를 업데이트하면 시스템이 자동으로 stateCode와 ibge를 해결합니다. cert_file과 cert_pwd를 함께 보내면 저장 전에 인증서가 검증됩니다.

회사는 NF-e 설정으로 생성됩니다(/api/company/create 통해). 다른 문서를 활성화하려면 여기에서 등록을 완료하세요: 이 엔드포인트는 NFC-e, NFS-e, MDF-e, CT-e, DC-e 필드도 허용합니다(아래 섹션 참조). 회사가 발행할 문서의 필드만 보내세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
company_id *	string	편집할 회사의 ID
name	string	회사명
invoice_type	string	세제
ie	string	주(州) 등록 번호
unit	string	단위 유형
email	string	이메일
cep	string	우편번호(`stateCode`와 `ibge` 자동 업데이트)
address	string	도로명 주소
house_number	string	번호
town	string	지구
city	string	도시
state	string	UF
cert_file	string	새 인증서(.pfx 또는 .p12)의 HTTPS URL. `cert_pwd`와 함께 보내면 저장 전에 검증됩니다
cert_pwd	string	새 인증서 비밀번호
serie	int	새 NF-e 시리즈
number	int	새 초기 번호
alias	string	상호
telefone	string	전화번호
complemento	string	주소 보충
NFC-e
csc_id	string	SEFAZ의 CSC(납세자 보안 코드) ID
csc	string	CSC 토큰(SEFAZ와 공유하는 비밀)
serie_nfce	int	NFC-e 시리즈
number_nfce	int	NFC-e 다음 번호
NFS-e
im	string	시 등록 번호 (Inscrição Municipal)
codigo_municipio_nfse	string	발행 도시의 IBGE 코드
codigo_servico_nfse	string	기본 서비스 코드 (LC 116)
cnae_nfse	string	기본 활동 CNAE
serie_nfse	int	NFS-e 시리즈
number_nfse	int	NFS-e 다음 번호
regime_especial_tributacao	int	특별 세제 코드
optante_simples_nacional	bool	Simples Nacional 가입
운송 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 시리즈
number_mdfe	int	MDF-e 시작 번호(번호 매기기 시작점)
serie_cte	int	CT-e 시리즈
number_cte	int	CT-e 시작 번호(번호 매기기 시작점)
serie_dce	int	DC-e 시리즈
number_dce	int	DC-e 시작 번호(번호 매기기 시작점)

* 필수 필드. cnpj를 보내면 오류를 반환합니다. 나머지 필드는 모두 선택 사항입니다 — 변경하려는 필드만 보내세요.

페이로드 예시

        {
          "company_id": "comp_789012",
          "name": "Nova Razão Social LTDA",
          "email": "novo@empresa.com",
          "cep": "01310100"
        }

예시 — 회사에 NFC-e와 CT-e 활성화

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

응답

        {
          "success": true
        }

GET /api/company/get_list

디스트리뷰터 회사 목록

디스트리뷰터(b2b) 계정에 연결된 발행 회사를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–20)

* 필수 필드.

호출 예시

GET /api/company/get_list?page=1&page_size=10

응답

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "UN",
                "email": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

인증된 회사 세부 정보

token 헤더로 식별된 회사의 전체 데이터를 등록된 세금 카테고리 목록과 함께 반환합니다. 본문이나 쿼리 문자열을 받지 않습니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

호출 예시

GET /api/company/get_detail

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "UN",
            "email": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/company/get_cep_detail

CEP로 주소 조회

브라질 CEP(우편번호)를 해결하여 UF, IBGE 자치단체 코드 및 주소 데이터를 반환합니다. 회사 및 고객 주소 입력에 유용합니다. 디스트리뷰터(b2b) 계정이 필요합니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
cep *	string	브라질 CEP(8자리, 하이픈 유무 관계없음)

* 필수 필드.

호출 예시

GET /api/company/get_cep_detail?cep=01001000

응답

        {
          "success": true,
          "data": {
            "cep": "01001-000",
            "uf": "SP",
            "ibge": 3550308,
            "logradouro": "Praça da Sé",
            "bairro": "Sé",
            "localidade": "São Paulo",
            "ddd": "11"
          }
        }

GET /api/company/get_export_invoice_month_files

생성된 월별 내보내기 파일 목록

현재 연도(시간대 America/Sao_Paulo)에 회사에 대해 이미 생성된 월별 내보내기 파일 목록을 반환합니다. 각 월에는 최대 4개 파일이 있을 수 있습니다: Excel 스프레드시트 1개(Success 상태만) + XML 3개(Success, Canceled, Voided 상태별). 실제로 내보내진 파일만 응답에 표시됩니다 — 새 파일을 생성하려면 /api/invoice/get_xml을 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

호출 예시

GET /api/company/get_export_invoice_month_files

응답

필드	타입	설명
files[]	array	사용 가능한 파일 목록
files[].url	string	OSS의 파일 URL
files[].year	int	기간 연도
files[].month	string	월(1–12)
files[].type	string	파일 형식: `"xlsx"` 또는 `"xml"`
files[].status	string	파일 내 송장의 상태: `"Success"`, `"Canceled"` 또는 `"Voided"`
files[].create	datetime	파일 생성 일시

응답 예시

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }

GET /api/category/get_list

제품 카테고리 목록

Returns all available categories for fiscal classification.

POST /api/invoice/create

새 송장 발행

NF-e(모델 55)를 발행합니다. 발행 회사는 token 헤더로 식별되며, 본문에 company_id를 보내지 마세요.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	초 단위 Unix 타임스탬프 (5분 유효 시간)

Body — 최상위 필드

필드	타입	설명
식별 및 거래
id	string	멱등성을 위한 클라이언트 측 고유 ID (중복 제거 키 구성)
nature_of_operation *	string	거래 성격 (예: "상품 판매")
transaction_type *	string	유형: `"0"`=입고, `"1"`=출고, `"2"`=수입, `"3"`=수출
model *	string	문서 모델: `"55"`=NF-e
issuance_type *	string	발행 유형 (`"1"`=일반, `"9"`=비상, 등)
ambiente *	string	`"1"`=운영, `"2"`=테스트
finalidade	string	용도: `"1"`=일반, `"2"`=보완, `"3"`=조정, `"4"`=반품
ref_nfe_chave	string	참조된 NF-e의 44자리 액세스 키 (보완/조정/반품용)
is_reopen	boolean	이전에 발행된 NF-e를 재오픈/덮어쓰기
dh_sai_ent	string	출입고 일시 (ISO 8601). 기본값: 현재 타임스탬프
금액 및 할인
total_discount_amount	decimal	송장 총 할인액
troco	decimal	거스름돈 (NFC-e에서 일반적)
seguro	decimal	보험액 (XML의 `vSeg`로 제품에 안분)
outras_despesas	decimal	기타 비용 (XML의 `vOutro`로 제품에 안분)
지표 및 추가 정보
ind_final	string	최종 소비자: `"0"`=B2B, `"1"`=B2C
ind_pres	string	현장 지표: `"1"`=대면, `"2"`=인터넷, `"3"`=전화 서비스 등
informacoes_complementares	string	보충 정보 (`infAdic.infCpl`에 기록됨)
informacoes_fisco	string	세무 당국용 정보 (`infAdic.infAdFisco`에 기록됨)

Body — `cliente` (객체, 필수)

국내 거래(transaction_type 0 또는 1)의 경우: cpf 또는 cnpj, name, endereco, bairro(최소 2자), city, uf, cep가 필수입니다. 수입/수출(transaction_type 2 또는 3)의 경우: name만 필수입니다.

필드	타입	설명
cpf	string	고객 CPF (cnpj 대체)
cnpj	string	고객 CNPJ (cpf 대체)
ie	string	주(州) 등록 번호 (Inscrição Estadual)
name *	string	회사명 / 고객명
endereco	string	주소(도로명)
complemento	string	주소 보충 정보
numero	string	주소 번호
bairro	string	지구 (국내 거래는 최소 2자)
city	string	도시
uf	string	주(UF) — CEP에서 해결된 UF로 덮어씁니다
cep	string	우편번호 (UF 및 도시 검증)
telefone	string	전화번호
email	string	이메일
id_estrangeiro	string	외국인 ID (수입/수출에서 사용)
c_pais	int	BACEN 국가 코드. 기본값: `1058` (브라질)
x_pais	string	국가명. 기본값: `"BRASIL"`

Body — `products[]` (배열, 최소 1개 항목)

각 제품은 과세 정보가 필요합니다: 사전 등록된 세금 카테고리에 대한 category_id 참조, 또는 인라인 구성을 위한 impostos/tax_info 객체 중 하나.

필드	타입	설명
codigo	string	제품 내부 코드
name *	string	제품 설명 (CJK 문자는 제거됨)
ncm *	string	8자리 NCM
cest	string	CEST 코드 (ICMS-ST 적용 시 필수)
gtin	string	GTIN / 바코드
gtin_tributavel	string	과세 단위 GTIN
count *	decimal	수량
unit *	string	상업 단위 (예: "UN", "KG", "MT")
unit_price *	decimal	단가
total_price *	decimal	항목 총액
discount_price	decimal	항목 할인
origem *	int	상품 원산지 (`0`=국내, `1`=해외—직접 수입 등)
indicador_total *	int	NF-e 총액에 포함: `0`=아니요, `1`=예
category_id	string	사전 등록된 세금 카테고리 ID (`impostos`/`tax_info`를 보내지 않으면 필수)
impostos	object	인라인 세금 구성 (`category_id` 대체). 아래 구조 참조
tax_info	object	`impostos` 별칭 (동일 구조)
disable_difal	boolean	이 항목의 DIFAL 계산 비활성화
desconta_icms_pis_cofins	boolean	이 품목에만 PIS/COFINS 과세표준에서 ICMS 공제 (카테고리 설정 재정의)
ii	object	수입세 — CFOP 3.xxx의 경우 필수. 아래 구조 참조
import_declarations	array	수입 신고서(DI) — `transaction_type="2"`의 경우 필수. 아래 구조 참조
nItemPed	int	구매 주문 품목 (I61). 루트의 `id`에서 가져온 `xPed`가 참조하는 주문 내 항목 일련번호. 유효 범위: 1–999999. 기본값: 생략.

Body — `products[].impostos` / `products[].tax_info`

필드	타입	설명
industria	string	기준 산업/세율 (별칭: `aliquota`)
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS CST/CSOSN
icms.industria	string	ICMS 산업
icms.tipo_pessoa	string	인격 유형 (PF/PJ)
icms.codigo_beneficio_fiscal	string	cBenef (세금 혜택 코드)
ipi
ipi.codigo_enquadramento	string	IPI 법적 분류 코드
ipi.situacao_tributaria	string	IPI CST
ipi.aliquota	string	IPI 세율
ipi.tipo_pessoa	string	인격 유형
pis
pis.situacao_tributaria	string	PIS CST
pis.aliquota	string	PIS 세율
pis.tipo_pessoa	string	인격 유형
cofins
cofins.situacao_tributaria	string	COFINS CST
cofins.aliquota	string	COFINS 세율
cofins.tipo_pessoa	string	인격 유형
is (선택세)
is.cenario	string	IS 시나리오
is.situacao_tributaria	string	IS CST
is.aliquota	string	IS 세율
is.tipo_pessoa	string	인격 유형
ibs_cbs (세제 개혁)
ibs_cbs.situacao_tributaria	string	IBS/CBS CST
ibs_cbs.tipo_pessoa	string	인격 유형
ibs_cbs.classificacao_tributaria	string	IBS/CBS 세금 분류
difal
difal.disable_difal	boolean	항목의 DIFAL 비활성화 (제품 수준 `disable_difal`의 대체)

Body — `products[].ii` (수입세)

필드	타입	설명
vBC	decimal	II 계산 기준
vDespAdu	decimal	통관 비용
vII	decimal	II 금액
vIOF	decimal	IOF 금액

Body — `products[].import_declarations[]`

필드	타입	설명
nDI	string	DI 번호
dDI	string (date)	DI 날짜
xLocDesemb	string	통관 장소
UFDesemb	string	통관 주(州)
dDesemb	string (date)	통관 일자
cExportador	string	수출자 코드
tpViaTransp	int	국제 운송 수단
tpIntermedio	int	중개 유형
vAFRMM	decimal	AFRMM 금액
additions	array	DI 추가 항목 (필드: `nAdicao`, `nSeqAdic`, `cFabricante`, `vDescDI`, `nDraw`)

Body — `shipping_address` / `delivery_address` (객체, 선택)

shipping_address는 픽업 위치(발행자와 다른 경우의 실제 출발지)입니다. delivery_address는 배송 위치(고객과 다른 경우의 실제 도착지)입니다. 지정 시 두 객체 모두 필수: cpf 또는 cnpj, name, endereco, bairro(최소 2자), city, uf, cep. 두 객체는 동일한 구조입니다.

필드	타입	설명
cpf	string	CPF (cnpj 대체)
cnpj	string	CNPJ (cpf 대체)
ie	string	주(州) 등록 번호
name *	string	회사명 / 이름
endereco *	string	주소
complemento	string	보충 정보
number	string	번호 (주의: 필드명은 `number`이며 `numero`가 아닙니다)
bairro *	string	지구
city *	string	도시
uf *	string	주
cep *	string	우편번호
telefone	string	전화번호
email	string	이메일

Body — `transportation` (객체, 선택)

transportation을 생략하면 시스템은 transport_mode="9"(운송료 없음)로 간주합니다.

필드	타입	설명
transport_mode	string	운송료 구분: `"0"`=발행자 부담, `"1"`=수령자 부담, `"2"`=제3자 부담, `"3"`=발송자 자체 운송, `"4"`=수령자 자체 운송, `"9"`=운송료 없음
freight_amount	decimal	총 운송료
carrier_info — 운송업체
carrier_info.cpf	string	운송업체 CPF (cnpj 대체)
carrier_info.cnpj	string	운송업체 CNPJ (cpf 대체)
carrier_info.ie	string	주(州) 등록 번호
carrier_info.name	string	회사명
carrier_info.endereco	string	주소
carrier_info.city	string	도시
carrier_info.uf	string	주
carrier_info.cep	string	우편번호
vehicle_info — 차량
vehicle_info.plate	string	번호판
vehicle_info.uf	string	번호판 주
vehicle_info.rntc	string	RNTC (국가 화물 운송업자 등록)
trailer_info — 트레일러 (vehicle_info와 동일 구조)
trailer_info.plate	string	트레일러 번호판
trailer_info.uf	string	주
trailer_info.rntc	string	RNTC
packages[] — 부피
packages[].qty	int	수량
packages[].gross_weight	decimal	총중량
packages[].net_weight	decimal	순중량
packages[].packaging_type	string	포장 유형
packages[].number	string	번호
packages[].mark	string	마크
packages[].seals	array<string>	봉인
transport_tax_retention_info — 운송료 ICMS 원천징수
transport_tax_retention_info.freight_service_amount	decimal	운송 서비스 금액
transport_tax_retention_info.tax_base	decimal	원천징수 계산 기준
transport_tax_retention_info.tax_rate	decimal	원천징수율
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	우편번호

Body — `pag_info[]` (배열, 선택)

생략 시 시스템은 [{ "payment_method": "01", "payment_indicator": "0" }](현금, 일시불)로 간주합니다.

필드	타입	설명
payment_method *	string	결제 방법: `"01"`=현금, `"02"`=수표, `"03"`=신용카드, `"04"`=직불카드, `"05"`=매장 신용, `"10"`=식료품권, `"11"`=식사권, `"15"`=은행 청구서, `"17"`=PIX, `"90"`=결제 없음, `"99"`=기타
payment_indicator *	string	구분: `"0"`=일시불, `"1"`=할부
payment_value	decimal	지불 금액
card_info — 카드 정보 (payment_method 03/04용)
card_info.integration_type *	string	단말기 연동 유형 (`card_info` 지정 시 필수)
card_info.brand_code *	string	카드 브랜드 (`card_info` 지정 시 필수)
card_info.acquirer_cnpj	string	매입사 CNPJ
card_info.authorization_code	string	승인 코드

* 필수 필드.

간소화된 예시

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "cliente": {
            "cpf": "12345678909",
            "name": "Cliente Exemplo",
            "endereco": "Rua Exemplo",
            "numero": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000",
            "email": "cliente@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Produto Exemplo",
              "ncm": "85176277",
              "count": 2,
              "unit": "UN",
              "unit_price": 150.00,
              "total_price": 300.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": 0,
              "indicador_total": 1
            }
          ],
          "pag_info": [
            { "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
          ]
        }

완전한 예시 (모든 필드)

        {
          "id": "PEDIDO-2026-0001",
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "finalidade": "1",
          "ref_nfe_chave": "",
          "is_reopen": false,
          "dh_sai_ent": "",
          "total_discount_amount": 0.00,
          "troco": 0.00,
          "seguro": 0.00,
          "outras_despesas": 0.00,
          "ind_final": "1",
          "ind_pres": "9",
          "informacoes_complementares": "Entrega via transportadora",
          "informacoes_fisco": "ICMS recolhido conforme legislação",
          "cliente": {
            "cpf": "",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Cliente Exemplo LTDA",
            "endereco": "Av. Paulista",
            "numero": "1000",
            "complemento": "Sala 200",
            "bairro": "Bela Vista",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "telefone": "11999998888",
            "email": "cliente@exemplo.com",
            "id_estrangeiro": "",
            "c_pais": 1058,
            "x_pais": "BRASIL"
          },
          "shipping_address": {
            "cnpj": "98765432000111",
            "name": "Depósito Origem LTDA",
            "ie": "987654321",
            "endereco": "Rua do Depósito",
            "number": "50",
            "complemento": "Galpão 3",
            "bairro": "Industrial",
            "city": "Guarulhos",
            "uf": "SP",
            "cep": "07000000",
            "telefone": "11988887777",
            "email": "deposito@exemplo.com"
          },
          "delivery_address": {
            "cnpj": "12345678000199",
            "name": "Cliente Exemplo LTDA",
            "ie": "123456789",
            "endereco": "Rua de Entrega",
            "number": "25",
            "complemento": "Loja 2",
            "bairro": "Centro",
            "city": "Campinas",
            "uf": "SP",
            "cep": "13010000",
            "telefone": "11977776666",
            "email": "entrega@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Notebook Dell",
              "ncm": "84713012",
              "cest": "",
              "gtin": "7891234567890",
              "gtin_tributavel": "7891234567890",
              "count": 2,
              "unit": "UN",
              "unit_price": 3500.00,
              "total_price": 7000.00,
              "discount_price": 0.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1
            },
            {
              "codigo": "PROD002",
              "name": "Mouse sem fio",
              "ncm": "84716053",
              "count": 5,
              "unit": "UN",
              "unit_price": 80.00,
              "total_price": 400.00,
              "origem": 0,
              "indicador_total": 1,
              "nItemPed": 2,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "00",
                  "industria": "",
                  "tipo_pessoa": "juridica",
                  "codigo_beneficio_fiscal": ""
                },
                "ipi": {
                  "codigo_enquadramento": "999",
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "pis": {
                  "situacao_tributaria": "01",
                  "aliquota": "0.65",
                  "tipo_pessoa": "juridica"
                },
                "cofins": {
                  "situacao_tributaria": "01",
                  "aliquota": "3.00",
                  "tipo_pessoa": "juridica"
                },
                "ibs_cbs": {
                  "situacao_tributaria": "000",
                  "tipo_pessoa": "juridica",
                  "classificacao_tributaria": "000001"
                }
              }
            }
          ],
          "transportation": {
            "transport_mode": "1",
            "freight_amount": 150.00,
            "carrier_info": {
              "cnpj": "11222333000144",
              "ie": "112223334",
              "name": "Transportadora Exemplo LTDA",
              "endereco": "Rod. BR-101, km 50",
              "city": "Santos",
              "uf": "SP",
              "cep": "11000000"
            },
            "vehicle_info": {
              "plate": "ABC1D23",
              "uf": "SP",
              "rntc": "12345"
            },
            "trailer_info": {
              "plate": "DEF4G56",
              "uf": "SP",
              "rntc": "67890"
            },
            "packages": [
              {
                "qty": 3,
                "gross_weight": 12.500,
                "net_weight": 11.000,
                "packaging_type": "CAIXA",
                "number": "001-003",
                "mark": "FRAGIL",
                "seals": ["LACRE001", "LACRE002"]
              }
            ],
            "transport_tax_retention_info": {
              "freight_service_amount": 150.00,
              "tax_base": 150.00,
              "tax_rate": 12.00,
              "cfop": "5932",
              "cep": "11000000"
            }
          },
          "pag_info": [
            {
              "payment_indicator": "1",
              "payment_method": "03",
              "payment_value": 7400.00,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH987654"
              }
            }
          ]
        }

GET /api/invoice/get_list

NF-e 목록(페이지네이션)

회사의 NF-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링(값: `"Success"`(승인됨), `"Canceled"`(취소됨), `"Voided"`(무효화됨), `"Processing"`(처리 중), `"InvoicingFailed"`(발행 실패), `"Failed"`(실패), `"Contingencia"`(오프라인 비상), `"Unknown"`(알 수 없음))

* 필수 필드.

호출 예시

GET /api/invoice/get_list?page=1&page_size=20&status=Success

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Success",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET /api/invoice/get_detail

NF-e 세부 정보 조회

UUID 또는 액세스 키로 특정 NF-e의 세부 정보를 반환합니다. XML URL, DANFE URL(전체, 간소화, 라벨) 및 메타데이터를 포함합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
uuid	string	NF-e UUID
chave	string	NF-e 액세스 키(44자리)

uuid 또는 chave 중 하나 이상을 입력하세요. 둘 다 보내면 uuid가 우선합니다.

호출 예시

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
GET /api/invoice/get_detail?chave=35210112345678901234567890123456789012345678

응답

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Success",
            "total_price": 300.00,
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave.pdf",
            "danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
            "danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/invoice/refresh

송장 상태 갱신

SEFAZ에서 NF-e의 현재 상태를 조회하고 로컬 레코드를 갱신합니다. 발행이 처리 중이거나 비상 상태로 남아 있을 때 유용합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	조회할 NF-e의 UUID

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

송장 취소

승인된 NF-e를 취소합니다. SEFAZ에 보내는 사유는 고정되어 있습니다: "Erro no preenchimento da nota fiscal." — 페이로드로 구성할 수 없습니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	취소할 NF-e의 UUID(`/api/invoice/create`에서 반환되는 내부 식별자)

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

번호 범위 무효화

승인되지 않은 NF-e 번호의 연속 범위를 무효화합니다(취소와 혼동하지 마세요 — 취소는 이미 승인된 송장에 적용됩니다). 이 작업은 SEFAZ에 기록되며 되돌릴 수 없습니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
modelo *	string	문서 모델: `"55"`=NF-e, `"65"`=NFC-e. (주의: 필드명은 `modelo`이며 `model`이 아닙니다)
ambiente *	string	`"1"`=운영, `"2"`=테스트
serie *	int	무효화할 번호의 시리즈
start_number *	int	범위 시작 번호
end_number *	int	범위 종료 번호
motivo *	string	무효화 사유 (SEFAZ 요구에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "modelo": "55",
          "ambiente": "2",
          "serie": 1,
          "start_number": 100,
          "end_number": 105,
          "motivo": "Falha no sistema durante a emissao do lote"
        }

POST /api/invoice/get_danfe

NF-e의 DANFE(PDF) 가져오기

NF-e DANFE의 세 URL을 반환합니다: 전체 DANFE(PDF), 간소화된 DANFE PDF(영수증 형식), 간소화된 DANFE PNG(라벨 이미지). PDF는 승인된 XML로부터 요청 시 생성되어 OSS에 캐싱됩니다. 후속 호출에서 송장 상태가 변경되지 않은 경우 기존 캐시가 반환됩니다. 상태가 변경된 경우(예: 송장이 취소됨), PDF가 재생성됩니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
uuid ⚠	string	NF-e 내부 UUID (`/api/invoice/create`가 반환)
chave ⚠	string	NF-e 액세스 키(44자리)

⚠ uuid 또는 chave 중 하나는 필수.

페이로드 예시

        {
          "uuid": "abc123-def456-..."
        }

응답

                {
                  "success": true,
                  "data": {
                    "danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
                    "danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
                    "danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
                  }
                }

응답 필드

필드	유형	설명
danfe	string	전체 DANFE PDF의 URL(A4 형식)
danfe_simples	string	간소화된 DANFE PDF의 URL(영수증 형식)
danfe_simples_png	string	간소화된 DANFE PNG(라벨 이미지) URL

오류 응답

메시지	원인
uuid/chave不能为空	`uuid`도 `chave`도 전송되지 않음
发票不存在	토큰 사용자의 송장을 찾을 수 없음 또는 승인된 XML 누락
发票详情不存在	송장 세부사항(프로토콜 포함)을 찾을 수 없음
获取PDF失败:<사유>	XML로부터 PDF 생성 실패

POST /api/invoice/get_xml

XML/Excel 일괄 내보내기(비동기)

사용자의 송장에 대한 비동기 일괄 내보내기 작업을 시작하며 기간과 상태로 필터링합니다. Excel 스프레드시트(메타데이터만) 또는 XML 포함 ZIP 패키지를 생성할 수 있습니다. 첫 번째 호출은 작업을 만들고 status: "Processing"을 반환합니다. 동일한 매개변수의 후속 호출은 진행 상황을 반환하며 status: "Success"가 되면 url 필드에 다운로드 링크가 포함됩니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
type *	string	출력 형식: `"excel"`(메타데이터 스프레드시트) 또는 기타 값(예: `"xml"`) - XML 포함 ZIP
status	string	송장 상태로 필터링(예: `"Success"`, `"Canceled"`, `"Voided"`). `type=excel`의 경우 내부적으로 소문자 처리
month	int	월(1–12). 제공된 경우 `start_create_time`/`end_create_time`을 대체; `America/Sao_Paulo` 타임존 및 현재 연도 사용(미래 월이면 전년도)
start_create_time	long	기간 시작(Unix 타임스탬프, 밀리초)
end_create_time	long	기간 종료(Unix 타임스탬프, 밀리초)

* 필수 필드.

페이로드 예시

        {
          "type": "xml",
          "status": "Success",
          "month": 5
        }

응답 — 처리 중

        {
          "success": true,
          "data": {
            "status": "Processing",
            "progress_count": 120,
            "total_count": 543,
            "url": ""
          }
        }

응답 — 완료

                {
                  "success": true,
                  "data": {
                    "status": "Success",
                    "progress_count": 543,
                    "total_count": 543,
                    "url": "https://storage.../exports/uid/.zip"
                  }
                }

응답 필드

필드	유형	설명
status	string	작업 실행 중에는 `"Processing"`, 파일이 준비되면 `"Success"`
progress_count	int	지금까지 처리된 송장 수
total_count	int	처리할 송장 총 수
url	string	최종 파일 다운로드 URL(`status = Processing` 동안은 빈 문자열)

멱등성: 작업은 매개변수 해시(uid + token + 기간 + status + type)로 중복 제거됩니다. 동일한 매개변수의 반복 호출은 새로운 실행을 트리거하지 않고 동일한 작업의 진행률을 반환합니다.

오류 응답

메시지	원인
发票类型字段不能为空	`type` 누락

POST /api/invoice/consultar_status

SEFAZ에서 NF-e/NFC-e 상태 조회

액세스 키(44자리)를 사용해 NfeConsultaProtocolo4 서비스를 통해 SEFAZ에서 직접 NF-e 또는 NFC-e의 현재 상태를 조회합니다. 토큰 회사가 발행한 자체 송장과 DistDFe로 캡처한 제3자 송장 모두 작동합니다. 모델(NF-e/NFC-e)은 키의 20-21 위치에서 자동으로 감지됩니다.

필수 헤더

헤더	유형	설명
token	string	회사 토큰(해당 인증서가 조회에 사용됨)
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
chave *	string	액세스 키(44자리 숫자). 발행자 UF는 0-1 위치에서 추출, 모델은 20-21 위치에서 추출(`55`=NF-e, `65`=NFC-e).

* 필수 필드.

페이로드 예시

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

응답

        {
          "success": true,
          "message": "Sucesso",
          "data": {
            "chave": "35260512345678000199550010000000011000000018",
            "status": "autorizada",
            "cstat": 100,
            "motivo": "Autorizado o uso da NF-e"
          }
        }

응답 필드

필드	유형	설명
chave	string	조회된 액세스 키
status	string	정규화된 상태(아래 표 참조)
cstat	int	SEFAZ의 원시 `cStat` 코드
motivo	string	SEFAZ의 원시 `xMotivo` 메시지

상태 매핑

`status`	SEFAZ cStat	의미
autorizada	`100`, `150`	사용 승인된 NF-e
cancelada	`101`, `151`	취소됨(`cStat=100`이라도 연결된 취소 이벤트가 있는 경우 반환)
denegada	`110`, `301`, `302`	SEFAZ에서 사용 거부
inutilizada	`102`	무효화된 번호(번호 범위)
nao_encontrada	`217`	NF-e가 SEFAZ 데이터베이스에 없음
desconhecido	기타	매핑되지 않은 cStat — 원시 `cstat`과 `motivo` 확인

오류 응답

메시지	원인
chave inválida: deve ter 44 dígitos	키 누락, 크기가 44가 아니거나 숫자가 아닌 문자 포함
empresa não possui certificado configurado	토큰 회사에 `cert_file`이 등록되어 있지 않음
SEFAZ retornou resposta vazia	SEFAZ가 응답을 반환하지 않음(타임아웃, 다운)
erro ao consultar SEFAZ: <세부정보>	서비스 호출 시 예외(잘못된 XML, 타임아웃, 만료된 인증서 등)

POST /api/category/create

세금 카테고리 생성

인증된 회사에 연결된 새 세금 카테고리(세금 템플릿)를 생성합니다. 각 카테고리는 ICMS, IPI, PIS, COFINS의 시나리오를 집계하며 선택적으로 IBS/CBS와 IS를 포함할 수 있습니다. 기존 카테고리를 편집하려면 /api/category/edit를 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body — 최상위

필드	타입	설명
descricao *	string	카테고리 설명
category_id	string	사용자 정의 ID. 생략 시 `"TF"` + 증분 번호로 자동 생성됨
disable_difal	boolean	이 카테고리의 DIFAL 계산 비활성화. 기본값: `false`
desconta_icms_pis_cofins	boolean	PIS/COFINS 과세표준에서 ICMS 공제 (과세표준 = vProd − vICMS). 기본값: `false`
icms[] *	array	ICMS 시나리오(구조는 아래)
ipi[] *	array	IPI 시나리오(구조는 아래)
pis[] *	array	PIS 시나리오(구조는 아래)
cofins[] *	array	COFINS 시나리오(구조는 아래)
ibs_cbs[]	array	IBS/CBS 시나리오 — 세제 개혁(구조는 아래)
is[]	array	IS 시나리오 — 선택세(구조는 아래)

Body — `icms[]`

필드	타입	설명
tipo_tributacao *	string	ICMS 과세 유형
cenario *	string	시나리오(예: `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS의 CST/CSOSN
nao_contribuinte	boolean	비납세 고객
aliquota_importacao	string	수입세율
aliquota_credito	decimal	크레딧 세율(Simples Nacional용 %)
aliquota_diferimento	decimal	이연 비율
aliquota_diferimentoFcp	string	FCP 이연(주의: 필드는 camelCase `diferimentoFcp`)
aliquota_reducao	decimal	ICMS 기준 감액 비율
aliquota_reducaoSt	decimal	ICMS-ST 기준 감액 비율(주의: `reducaoSt` camelCase)
motivo_desoneracao	string	ICMS 면세 사유 코드
motivo_desoneracaoSt	string	ICMS-ST 면세 사유 코드(주의: camelCase)
주(州)별 세율 — 선택
aliquota_mva[]	array	UF별 MVA — 항목: `{ estado, aliquota }`
aliquota_icms[]	array	UF별 ICMS 세율 — 항목: `{ estado, aliquota }`
aliquota_icms_st[]	array	UF별 ICMS-ST 세율 — 항목: `{ estado, aliquota }`
aliquota_fcp[]	array	UF별 FCP 세율 — 항목: `{ estado, aliquota }`
aliquota_fcp_st[]	array	UF별 FCP-ST 세율 — 항목: `{ estado, aliquota }`
beneficio_fiscal[]	array	UF별 세금 혜택 코드 — 항목: `{ estado, codigo }`

Body — `ipi[]`

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IPI의 CST
codigo_enquadramento *	string	법적 분류 코드
aliquota *	string	IPI 세율

Body — `pis[]` 및 `cofins[]`(동일 구조)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	PIS/COFINS의 CST
aliquota *	string	세율

Body — `ibs_cbs[]`(세제 개혁)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IBS/CBS의 CST
classificacao_tributaria *	string	세금 분류

Body — `is[]`(선택세)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IS의 CST
aliquota *	string	IS 세율

* 필수 필드.

최소 예시

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
          "pis":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
          "cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

세금 카테고리 세부 정보

세금 카테고리의 전체 구성을 반환합니다: 모든 ICMS, IPI, PIS, COFINS, IBS/CBS 시나리오, UF별 배열(MVA, 세율, 세금 혜택)을 포함합니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
category_id *	string	세금 카테고리 ID

* 필수 필드.

호출 예시

GET /api/category/get_detail?category_id=TF123

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
            "pis":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
            "cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
            "ibs_cbs":[]
          }
        }

GET /api/category/get_list

세금 카테고리 목록

인증된 회사의 세금 카테고리를 페이지네이션으로 나열합니다. 각 항목에 대해 category_id와 descricao만 반환합니다 — 전체 구성을 보려면 /api/category/get_detail을 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)

* 필수 필드.

호출 예시

GET /api/category/get_list?page=1&page_size=20

응답

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
              { "category_id": "TF124", "descricao": "Devolução de venda" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/category/edit

세금 카테고리 편집

기존 세금 카테고리를 편집합니다. 본문은 /api/category/create와 동일하며, 유일한 차이점은 category_id가 필수이고 기존 카테고리와 일치해야 한다는 점입니다. Upsert는 icms, ipi, pis, cofins, ibs_cbs, is 배열을 완전히 대체합니다 — 업데이트된 모든 시나리오를 보내세요(시나리오 단위 병합 없음).

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

전체 본문 구조는 /api/category/create에 문서화되어 있습니다. 여기서는 category_id만 다르게 처리됩니다:

필드	타입	설명
category_id *	string	편집할 카테고리의 ID(존재해야 하며, 아니면 오류 반환)
descricao *	string	설명
icms[] *	array	ICMS 시나리오(완전 대체)
ipi[] *	array	IPI 시나리오
pis[] *	array	PIS 시나리오
cofins[] *	array	COFINS 시나리오
ibs_cbs[]	array	IBS/CBS 시나리오(선택)
is[]	array	IS 시나리오(선택)
disable_difal	boolean	기본값: `false`
desconta_icms_pis_cofins	boolean	기본값: `false`

* 필수 필드. 각 배열의 내부 필드(icms[].codigo_cfop 등)는 /api/category/create를 참조하세요.

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

POST /api/category/delete

세금 카테고리 삭제

회사에서 세금 카테고리를 제거합니다. 되돌릴 수 없는 작업입니다. 이 카테고리에 연결된 제품은 삭제된 category_id를 계속 참조하므로 NFe 발행이 실패합니다 — 삭제 전에 제품을 업데이트하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
category_id *	string	삭제할 카테고리의 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF123"
        }

응답

        {
          "success": true
        }

POST /api/invoice/return

반품 NF-e 발행

원본 NF-e에서 반품 NF-e(모델 55, 용도 4)를 발행합니다. 두 가지 모드를 지원합니다: 전체 반품(uuid 또는 chave로 원본 인보이스 참조 — 반품은 원본 NF-e의 완전한 복제) 또는 부분/사용자 정의 반품(chave + 인보이스의 전체 필드를 본문에 직접 전송. /api/invoice/create와 동일한 구조).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body — 최상위 필드

필드	타입	설명
uuid	string	원본 NF-e의 UUID(전체 반품용. `chave`가 없으면 필수). 전송하면 항상 전체 반품이 되며 부분 반품 필드는 무시됩니다
chave	string	원본 NF-e의 44자리 액세스 키(부분 반품에서는 필수. 전체 반품에서는 `uuid`의 대안)
cfop *	string	반품 CFOP(예: `"1202"`, `"1411"`, `"2202"`, `"5202"`, `"5411"`, `"6202"`)
natureza_operacao	string	거래 성격(예: "Devolução de venda"). 별칭 허용: `nature_of_operation`
transaction_type	string	거래 유형: `"0"`=입고, `"1"`=출고(부분 반품에서는 필수). 반품 NF-e는 항상 입고(`tpNF=0`)로 발행됩니다
model	string	문서 모델: `"55"`(부분 반품에서는 필수)
issuance_type	string	발행 유형: `"1"`=일반(부분 반품에서는 필수)
ambiente	string	환경: `"1"`=운영, `"2"`=테스트(부분 반품에서는 필수)
cliente	object	수취인 데이터. `/api/invoice/create`와 동일한 구조(부분 반품에서는 필수). 주의 사항: 주소 번호 필드는 `number`(영어)이며 `numero`가 아닙니다. `number`가 없으면 주소는 nro "S/N"으로 출력됩니다. IBGE 코드·도시·주(UF)는 `cep`로 결정됩니다
products	array	반품 품목. `/api/invoice/create`와 동일한 구조(부분 반품에서는 필수). `codigo`는 선택 사항 — 없으면 cProd에 `name`이 사용됩니다

* 필수 필드. uuid 또는 chave도 필수입니다(둘 중 하나만).

반품 시 자동 처리: 결제는 90(결제 없음)으로 출력되며 pag_info는 무시됩니다. natureza_operacao를 보내지 않으면 "Devolução de Mercadoria"가 사용됩니다. 품목의 세무 정보(CST/CSOSN, PIS/COFINS, IPI, IBS/CBS)는 category_id의 세무 카테고리에서 개인/법인 구분과 시나리오에 따라 결정됩니다.

예시 — 전체 반품

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

예시 — 부분 반품(전체 필드를 본문에 기재)

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução parcial",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "cliente": {
            "cnpj": "12345678000199",
            "name": "Fornecedor",
            "endereco": "...",
            "bairro": "...",
            "city": "...",
            "uf": "SP",
            "cep": "01001000"
          },
          "products": [
            {
              "name": "...",
              "ncm": "...",
              "count": 1,
              "unit": "UN",
              "unit_price": 100,
              "total_price": 100,
              "category_id": "...",
              "origem": 0,
              "indicador_total": 1
            }
          ]
        }

code 완전한 송장 발행 예시

운송 포함 완전한 예시

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_final": "0",
          "ind_pres": "1",
          "cliente": {
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Empresa Cliente Ltda",
            "endereco": "Rua Exemplo",
            "number": "123",
            "complemento": "Sala 45",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01234567",
            "telefone": "11999999999",
            "email": "contato@empresa.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Smartphone XYZ",
              "ncm": "85171210",
              "cest": "2804000",
              "count": 2,
              "unit": "UN",
              "unit_price": 1500.00,
              "total_price": 3000.00,
              "category_id": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da Transportadora",
              "city": "São Paulo",
              "uf": "SP"
            },
            "vehicle_info": {
              "plate": "ABC1234",
              "uf": "SP",
              "rntc": "123456"
            },
            "packages": [
              {
                "qty": 1,
                "packaging_type": "CX",
                "gross_weight": 2.500,
                "net_weight": 2.000
              }
            ]
          },
          "shipping_address": {
            "cnpj": "12345678000199",
            "name": "Remetente Ltda",
            "endereco": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "number": "200",
            "bairro": "Centro",
            "city": "Rio de Janeiro",
            "uf": "RJ",
            "cep": "20040020"
          },
          "pag_info": [
            {
              "payment_method": "03",
              "payment_indicator": "0",
              "card_info": {
                "integration_type": "1",
                "brand_code": "01"
              }
            }
          ],
          "informacoes_complementares": "Sem informações adicionais",
          "informacoes_fisco": "ICMS recolhido conforme legislação"
        }

💡 정보: 이 예시에는 모든 중요한 필드가 포함되어 있으며, 운송, 상세 세무 정보 및 결제를 포함합니다. 특정 필요에 따라 값을 조정하십시오.

수입 완전한 예제

        {
          "id": "PED-IMP-001",
          "nature_of_operation": "Importacao para revenda",
          "transaction_type": "2",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "finalidade": "1",
          "ind_final": "0",
          "ind_pres": "9",
          "cliente": {
            "name": "EXPORTADOR EXTERIOR CO LTD",
            "endereco": "Pudong District",
            "numero": "456",
            "city": "Shanghai",
            "id_estrangeiro": "CN-EXP-001",
            "c_pais": 1600,
            "x_pais": "CHINA"
          },
          "products": [
            {
              "name": "Fonte chaveada 12V 2A Quickfitting",
              "codigo": "123450000888",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 0.01,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 1,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            },
            {
              "name": "Quick fitting MA",
              "codigo": "123450000157",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "ii": {
                "vBC": 0.50,
                "vDespAdu": 0.00,
                "vII": 0.00,
                "vIOF": 0.00
              },
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 1.00,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 2,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

💡 정보: NFe 수입 예시 (CFOP 3.xxx). 국내 NFe와의 차이점:

transaction_type: "2" — 입고(수입) 작업.
cliente는 cnpj/cpf/uf/cep 없음. id_estrangeiro, c_pais(BACEN 테이블 — 중국 = 1600), x_pais 사용.
category_id는 CFOP 3.xxx 및 수입과 호환되는 CST/CSOSN을 가진 세무 카테고리를 가리켜야 합니다.
제품의 origem = 1(외국 — 직수입) 또는 2(외국 — 국내 시장에서 구매).
ii 블록(수입세)은 CFOP가 3.xxx일 때 필수입니다. 값은 통관사가 발행한 DI에서 가져옵니다(vBC, vDespAdu, vII, vIOF). 테스트에서는 0이 될 수 있습니다.
import_declarations 블록(수입 신고)에는 통관 데이터가 포함됩니다: nDI, dDI, 통관 장소/UF/날짜, 운송 방식, 중개인, 수출자 및 추가 정보.
vAFRMM은 tpViaTransp = 1(해상)일 때 필수입니다.

percent 상세 세무 파라미터

scale_balance ICMS 파라미터

과세 시나리오

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

세무 상황(CST)

00: 전액 과세

02: 과세(면제 취급)

10: ICMS 징수를 동반한 과세

20: 과세표준 경감

30: 면세 또는 비과세

40: 면세

41: 비과세

50: 정지

51: 이연

60: ICMS 기징수

70: 경감 및 징수

90: 기타

pie_chart PIS/COFINS 파라미터

과세 시나리오

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

세무 상황(CST)

01: 과세 거래(일반 세율)

02: 과세 거래(차등 세율)

03: 과세 거래(면세)

04: 과세 거래(정지)

05: 과세 거래(ST)

06: 과세 거래(영세율)

07: 기여금 면제 거래

08: 기여금 비과세 거래

09: 기여금 정지 거래

49: 기타 출고 거래

50: 공제권(자체 거래)

51: 공제권(매입)

52: 대변 기장

53: 차변 기장

54: 대변 기장(기한 외)

55: 차변 기장(기한 외)

56: 추정 공제

60: 추정 공제(매입)

61: 추정 공제(수입)

62: 추정 공제(농업 활동)

63: 추정 공제(기타)

64: 추정 공제(비발생)

65: 추정 공제(대체)

66: 추정 공제(대체)

67: 추정 공제(수출)

70: 공제권 없는 매입 거래

71: 면제 매입 거래

72: 정지 매입 거래

73: 영세율 매입 거래

74: 비과세 매입 거래

75: 대체에 의한 매입 거래

98: 기타 입고 거래

99: 기타 거래

💡 정보: tipo_pessoa 필드는 fisica(개인) 또는 juridica(법인)를 허용합니다. PIS/COFINS의 경우 aliquota 필드는 소수점 두 자리 문자열 (예: "1.65")로 포맷해야 합니다.

credit_card 결제 파라미터

결제 지표

`0`	일시불(즉시)
`1`	후불

결제 방법

`01`	현금
`02`	수표
`03`	신용카드
`04`	직불카드
`05`	매장 크레딧
`10`	식품 바우처(Vale Alimentação)
`11`	식사 바우처(Vale Refeição)
`12`	상품권
`13`	연료 바우처
`15`	은행 송금표
`90`	결제 없음
`99`	기타

카드 브랜드

`01`	Visa
`02`	Mastercard
`03`	American Express
`04`	Sorocred
`05`	Diners Club
`06`	Elo
`07`	Hipercard
`08`	Aura
`09`	Cabal
`99`	기타

bug_report XML 문제 해결

warning 거부 225 - XML 스키마 오류

SEFAZ 데이터베이스에 정상적으로 등록되지 않은 NF-e에 대해 취소, XML 다운로드, 번호 무효화 또는 매니페스트 등록을 시도할 때 발생합니다.

NF-e가 승인되었는지 확인(상태 "승인됨")

승인되지 않은 경우 NF-e 재발행

사용하지 않은 경우 번호 무효화

lightbulb SEFAZ 온라인 검증

공식 검증기를 사용하여 XML 문제를 확인:


                  https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

일반적인 문제: 불완전한 주소, 유효하지 않은 NCM, 잘못된 값 형식, 필수 필드 누락.

error SEFAZ 오류 코드

코드	설명	해결책
`217`	발행일이 너무 오래됨	컨틴전시로 발행하거나 정규화
`404`	수신자 CNPJ/CPF 무효	고객 서류 확인
`563`	거래에 허용되지 않는 CFOP	거래의 CFOP 재검토

POST /api/nfce/company/create

NFC-e용 회사 등록

NFC-e 발급용 회사를 등록(또는 업데이트)합니다. 회사명, IE, 주소 및 기타 데이터는 CNPJ에서 SintegraWS를 통해 자동 추출됩니다. CNPJ가 이미 사용자에게 존재하면 NFC-e 필드가 업데이트되고 기존 회사가 반환됩니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cnpj *	string	발행 회사 CNPJ
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
csc_id *	string	SEFAZ의 CSC(납세자 보안 코드) ID
csc *	string	CSC 토큰(SEFAZ와 공유하는 비밀)
serie_nfce	int	NFC-e 시리즈
number_nfce	int	NFC-e 초기 번호
telefone	string	회사 전화번호

* 필수 필드. 기타 데이터(이름, IE, 주소 등)는 CNPJ에서 SintegraWS를 통해 자동 추출됩니다.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

응답

        {
          "success": true,
          "message": "Empresa cadastrada para NFC-e",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

NFC-e 회사 데이터 업데이트

token 헤더로 식별되는 NFC-e 회사를 업데이트합니다. Body의 모든 필드는 선택 사항입니다 — 변경하려는 필드만 보내세요. cep를 업데이트하면 시스템이 자동으로 stateCode와 ibge를 해결합니다. cert_file과 cert_pwd가 함께 오면 인증서는 저장 전에 검증됩니다.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body(모든 필드 선택 — 최소 1개 전송)

필드	타입	설명
식별
name	string	회사명
alias	string	상호
ie	string	주(州) 등록 번호
invoice_type	string	세제
email	string	이메일
telefone	string	전화번호
주소
cep	string	우편번호(`stateCode`와 `ibge` 자동 업데이트)
address	string	도로명 주소
house_number	string	번호
complemento	string	보충
town	string	지구
city	string	도시
state	string	UF
NFC-e
csc_id	string	CSC ID
csc	string	CSC 토큰
serie_nfce	int	시리즈
number_nfce	int	다음 번호
cert_file	string	새 A1 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd	string	인증서 비밀번호

Body의 최소 1개 필드가 필수입니다. CNPJ는 변경할 수 없습니다.

페이로드 예시

        {
          "alias": "Loja Centro - Filial 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

응답

        {
          "success": true,
          "message": "Empresa NFC-e atualizada com sucesso"
        }

POST /api/nfce/company/get

NFC-e 회사 조회

token 헤더로 식별되는 NFC-e 회사 데이터를 반환합니다. 주의: 메서드는 POST이지만 본문 필드는 필요하지 않습니다 — 회사는 토큰만으로 식별됩니다.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

비어 있음. {}를 보낼 수 있습니다.

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Loja Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

NFC-e Fiscal Category Management

Fiscal categories define the tax rules applied to products when issuing NFC-e. Unlike NFe, NFC-e only operates with intrastate sales, so the structure is simplified: a single object per tax type, without the need for multiple scenarios.

참고: NFC-e categories are stored separately from NFe categories. Each category includes ICMS, PIS, COFINS, and IBS/CBS settings. All endpoints in this section require the token, sign, and timestamp headers.

POST /api/nfce/category/create

NFC-e 세무 카테고리 생성

NFC-e 세무 카테고리를 생성합니다. 각 카테고리는 단일 시나리오(내부 출고)를 가지며 ICMS, PIS, COFINS, IBS/CBS에 플랫 객체를 사용합니다(NFC-e는 카테고리당 여러 시나리오를 허용하지 않으므로 배열이 아닙니다). IPI는 없습니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body (루트)

필드	유형	설명
descricao *	string	카테고리 설명
codigo_cfop *	string	CFOP 코드 (예: 5102, 5405)
icms *	object	ICMS 설정 (플랫 객체)
pis *	object	PIS 설정 (플랫 객체)
cofins *	object	COFINS 설정 (플랫 객체)
ibs_cbs	object	IBS/CBS 설정 (세제 개혁, 선택사항)

icms

필드	유형	설명
situacao_tributaria *	string	CST/CSOSN (예: 102, 500)
aliquota_reducao	decimal	과세표준 감면 비율
motivo_desoneracao	string	면제 사유 코드
aliquota_icms	array	주별 세율: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	주별 FCP: `[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	주별 세제 혜택: `[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

필드	유형	설명
situacao_tributaria *	string	PIS/COFINS CST
aliquota *	string	퍼센트 세율 (예: "0.00", "1.65", "7.60")

ibs_cbs (선택사항)

필드	유형	설명
situacao_tributaria *	string	IBS/CBS CST
classificacao_tributaria *	string	세무 분류 코드

* 필수 필드.

페이로드 예시

        {
          "descricao": "Bebidas não alcoólicas",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

GET /api/nfce/category/get_detail

NFC-e 세무 카테고리 상세 조회

NFC-e 세무 카테고리의 전체 데이터(설명, CFOP, ICMS, PIS, COFINS, IBS/CBS)를 반환합니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

쿼리 문자열

필드	유형	설명
category_id *	string	NFC-e 카테고리 ID

* 필수 필드.

요청 예시

GET /api/nfce/category/get_detail?category_id=TF00001

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_icms": [
                { "estado": "SP", "aliquota": 18.00 }
              ],
              "aliquota_fcp": [
                { "estado": "SP", "aliquota": 0.00 }
              ],
              "beneficio_fiscal": [
                { "estado": "SP", "codigo": "SP800001" }
              ]
            },
            "pis": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001"
            }
          }
        }

GET /api/nfce/category/get_list

NFC-e 세무 카테고리 목록

인증된 회사에 등록된 NFC-e 세무 카테고리의 페이지네이션 목록을 반환합니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

쿼리 문자열

필드	유형	설명
page *	int	페이지 번호 (최소 1)
page_size *	int	페이지당 항목 수 (1~50)

* 필수 필드.

요청 예시

GET /api/nfce/category/get_list?page=1&page_size=20

응답

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
              { "category_id": "TF00002", "descricao": "Alimentos industrializados" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/nfce/category/edit

NFC-e 세무 카테고리 편집

참고: /api/nfce/category/create 엔드포인트와 동일한 구조이며, 추가 필수 필드 category_id가 있습니다. icms, pis, cofins, ibs_cbs 필드는 완전히 대체됩니다(병합되지 않음).

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

추가 필드

필드	유형	설명
category_id *	string	편집할 카테고리 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF00001",
          "descricao": "Bebidas não alcoólicas — atualizado",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

POST /api/nfce/category/delete

NFC-e 세금 카테고리 삭제

NFC-e 세금 카테고리를 제거합니다. 되돌릴 수 없는 작업입니다. 이 카테고리에 연결된 제품은 삭제된 category_id를 계속 참조하므로 — 먼저 업데이트하세요.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
category_id *	string	삭제할 NFC-e 카테고리의 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF123"
        }

응답

        {
          "success": true
        }

POST /api/nfce/create

NFC-e 발행

NFC-e(모델 65, 항상 주 내 출고, 운송 없음)를 발행합니다. NFe 엔드포인트와의 주요 차이점: 소비자 객체는 client(cliente가 아님); 주소 번호는 client.number; 소비자는 선택사항; impostos.ipi, shipping_address, delivery_address, transportation는 존재하지 않음. pag_info의 금액 필드 이름은 amount.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body (루트)

필드	유형	설명
nature_of_operation *	string	거래 성격 (예: "상품 판매")
issuance_type *	string	발행 유형: "1" (정상), "9" (NFC-e 오프라인 비상)
ambiente *	string	"1" 운영, "2" 호몰로게이션
products *	array	상품 목록 (아래 참조)
id	string	외부 식별자
ind_pres	string	구매자 임석: "1" 대면(기본값), "4" 가정 배송, "5" 시설 외 대면, "9" 해당 없음
ind_intermed	string	"0" 중개자 없음, "1" 마켓플레이스. `ind_pres` = 2, 3, 4일 때 필수
total_discount_amount	decimal	송장 총 할인
troco	decimal	거스름돈 금액
seguro	decimal	보험 금액
outras_despesas	decimal	기타 부대 비용
informacoes_complementares	string	소비자 보충 정보
informacoes_fisco	string	세무 당국 관심 정보
client	object	소비자 데이터 (선택사항 — 아래 표 참조)
pag_info	array	결제 (기본값: 현금 — 아래 표 참조)

client (선택사항)

소비자가 식별된 경우에만 입력하세요. CPF 또는 CNPJ는 숫자만 전송해야 합니다.

필드	유형	설명
cpf	string	CPF (개인 설정)
cnpj	string	CNPJ (법인)
ie	string	주 등록 번호
name	string	이름 / 법인명
endereco	string	도로명
number	string	주소 번호 (주의: NFe는 `numero`를 사용)
complemento	string	보충
bairro	string	동네
city	string	도시
uf	string	주 (CEP 제공 시 검증됨)
cep	string	우편번호 (숫자만)
telefone	string	전화
email	string	이메일

products[] (각 항목)

필드	유형	설명
name *	string	상품명 (CJK 문자는 제거됨)
ncm *	string	NCM (8자리)
count *	decimal	수량
unit *	string	상업 단위 (예: "UN", "KG")
unit_price *	decimal	단가
total_price *	decimal	항목 총액
origem *	int	상품 원산지 (0..8)
indicador_total *	int	1 = 송장 총액 구성; 0 = 구성하지 않음
category_id ⚠	string	NFC-e 세무 카테고리 ID (`impostos` 미전송 시 필수)
impostos ⚠	object	수동 세금 (`category_id`의 대안, IPI 없음)
tax_info ⚠	object	`impostos`의 별칭 (동일한 구조). `impostos` 누락 시에만 사용
codigo	string	내부 상품 코드
cest	string	CEST
gtin	string	상업 GTIN/EAN
gtin_tributavel	string	과세 GTIN
discount_price	decimal	항목 할인
nItemPed	int	구매 주문 품목 (I61). 루트의 `id`에서 가져온 `xPed`가 참조하는 주문 내 항목 일련번호. 유효 범위: 1–999999. 기본값: 생략.

pag_info[] (각 항목)

필드	유형	설명
payment_indicator *	string	"0" 현금, "1" 신용
payment_method *	string	결제 방법 (01=현금, 03=신용카드, 04=직불카드, 17=PIX, 99=기타 등)
amount	decimal	이 방법으로 결제된 금액
card_info.integration_type	string	"1" 통합, "2" 비통합 (카드 03/04 시 필수)
card_info.brand_code	string	카드 브랜드 (카드 03/04 시 필수)
card_info.acquirer_cnpj	string	결제 대행사 CNPJ
card_info.authorization_code	string	승인 코드

* 필수 필드. ⚠ category_id, impostos, tax_info 중 하나는 필수.

간소화된 예시

        {
          "nature_of_operation": "Venda de mercadoria",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_pres": "1",
          "client": {
            "cpf": "12345678909",
            "name": "Consumidor Final"
          },
          "products": [
            {
              "name": "Refrigerante 2L",
              "ncm": "22021000",
              "count": 2,
              "unit": "UN",
              "unit_price": 10.50,
              "total_price": 21.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001"
            }
          ],
          "pag_info": [
            {
              "payment_indicator": "0",
              "payment_method": "17",
              "amount": 21.00
            }
          ]
        }

완전한 예시 (모든 필드)

        {
          "id": "PEDIDO-2026-0001",
          "nature_of_operation": "Venda de mercadoria",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_pres": "1",
          "ind_intermed": "0",
          "total_discount_amount": 0.00,
          "troco": 0.00,
          "seguro": 0.00,
          "outras_despesas": 0.00,
          "informacoes_complementares": "Pedido entregue na loja",
          "informacoes_fisco": "ICMS recolhido conforme legislação",
          "client": {
            "cpf": "12345678909",
            "cnpj": "",
            "ie": "",
            "name": "Consumidor Final",
            "endereco": "Rua das Flores",
            "number": "100",
            "complemento": "Sala 5",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000",
            "telefone": "11999998888",
            "email": "cliente@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Refrigerante 2L",
              "ncm": "22021000",
              "cest": "0300100",
              "gtin": "7891234567890",
              "gtin_tributavel": "7891234567890",
              "count": 2,
              "unit": "UN",
              "unit_price": 10.50,
              "total_price": 21.00,
              "discount_price": 0.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1
            },
            {
              "codigo": "PROD002",
              "name": "Salgadinho 100g",
              "ncm": "19053100",
              "count": 1,
              "unit": "UN",
              "unit_price": 8.00,
              "total_price": 8.00,
              "origem": 0,
              "indicador_total": 1,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "102",
                  "industria": "",
                  "tipo_pessoa": "juridica"
                },
                "pis": {
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "cofins": {
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "ibs_cbs": {
                  "situacao_tributaria": "000",
                  "tipo_pessoa": "juridica",
                  "classificacao_tributaria": "000001"
                }
              }
            }
          ],
          "pag_info": [
            {
              "payment_indicator": "0",
              "payment_method": "03",
              "amount": 24.00,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH123456"
              }
            }
          ]
        }

응답

        {
          "success": true,
          "data": {
            "uuid": "abc123...",
            "chave": "35..."
          }
        }

POST /api/nfce/cancel

NFC-e 취소

승인된 NFC-e를 취소합니다. NFe와 달리 취소 사유는 클라이언트가 제공하고 SEFAZ로 전달됩니다. SEFAZ 취소 창은 짧습니다(보통 승인 후 15-30분).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chave *	string	NFC-e의 44자리 액세스 키(주의: 다른 엔드포인트의 `uuid`가 아니라 `chave`입니다)
motivo *	string	취소 사유(SEFAZ 요구에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

GET /api/nfce/get_detail

NFC-e 세부 정보 조회

UUID로 특정 NFC-e의 세부 정보를 반환합니다. XML과 DANFE(영수증) URL, 제공된 경우 고객 데이터를 포함합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
uuid *	string	NFC-e UUID

* 필수 필드.

호출 예시

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

응답

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234650010000000051234567890",
            "serie": 1,
            "number": 5,
            "status": "Success",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

NFC-e DANFE(영수증) 생성/가져오기

NFC-e DANFE(전자 재정 영수증)의 PDF URL을 반환합니다. SEFAZ 조회용 QR 코드를 포함합니다. 필요에 따라 생성되며 해시(액세스 키 + 상태)로 캐시됩니다. 반복 호출 시 기존 URL을 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	NFC-e UUID(주의: 여기서는 `uuid`이며, `cancel`의 `chave`와 다릅니다)

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

응답

        {
          "success": true,
          "data": {
            "danfe": "https://oss.example.com/.../chave_nfce.pdf"
          }
        }

GET /api/nfce/get_list

NFC-e 목록(페이지네이션)

회사의 NFC-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링. 값: `"Success"`(승인됨), `"Canceled"`(취소됨), `"Processing"`(처리 중), `"Failed"`(실패), `"Unknown"`(알 수 없음)

* 필수 필드.

호출 예시

GET /api/nfce/get_list?page=1&page_size=20&status=Success

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35260112345678000190650010000000011000000017",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

code NFC-e Complete Examples

Example 1 — In-Person Sale (no recipient)

        {
          "nature_of_operation": "Venda de mercadoria",
          "ambiente": "2",
          "ind_pres": "1",
          "products": [
            {
              "codigo": "001",
              "name": "Refrigerante 350ml",
              "ncm": "22021000",
              "count": 3,
              "unit": "UN",
              "unit_price": 5.50,
              "total_price": 16.50,
              "category_id": "BEBIDAS_PADRAO",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            { "payment_indicator": "0", "payment_method": "17" }
          ]
        }

Example 2 — Home Delivery (with recipient)

        {
          "nature_of_operation": "Venda de mercadoria",
          "ambiente": "2",
          "ind_pres": "4",
          "client": {
            "cpf": "12345678900",
            "name": "Maria Silva",
            "endereco": "Rua das Flores",
            "number": "456",
            "bairro": "Jardim Primavera",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "04567000"
          },
          "products": [
            {
              "codigo": "PIZZA01",
              "name": "Pizza Grande Marguerita",
              "ncm": "19059090",
              "count": 1,
              "unit": "UN",
              "unit_price": 45.90,
              "total_price": 45.90,
              "category_id": "ALIMENTOS",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            { "payment_indicator": "0", "payment_method": "03" }
          ],
          "frete": 8.00,
          "informacoes_complementares": "Entrega em até 40 minutos"
        }

tune NFe Adjustment / Supplementary

Supplementary NFe and Adjustment NFe are invoices issued to correct tax values of an already authorized invoice. Unlike CC-e, which only corrects registration data, these invoices allow changing tax amounts, quantities, and prices.

Supplementary NFe (finalidade = 2):

Used to add values that were reported lower than correct in the original invoice
Price supplement, quantity, or tax amount
Example: issued invoice with 12% ICMS but the correct rate was 18% — issue supplementary with the difference

Adjustment NFe (finalidade = 3):

Used for various tax adjustments provided by legislation
Inventory adjustment, credit transfer, tax regularization
Example: ICMS adjustment by assessment, credit transfer between branches

중요:

Both are new invoices — they generate a new access key and new number
Must reference the original invoice via the ref_nfe_chave field (44-digit key)
The original invoice must be authorized
Each consumes 1 credit (same as a regular issuance)

인증

NFe 발행과 동일한 엔드포인트 및 인증을 사용합니다:

헤더	타입	설명
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

description NFS-e - 전자 서비스 청구서

NFS-e API는 전자 서비스 청구서의 발행, 취소 및 조회를 가능하게 합니다. 시스템은 자동으로 기업의 시/군을 감지하고 올바른 API로 라우팅합니다:

상파울루 (SP) - Nota Fiscal Paulistana (SOAP)를 통한 발행
기타 시/군 - 국가 API (ADN/SEFIN)를 통한 발행

통합자는 어떤 API를 사용할지 걱정할 필요가 없습니다. 데이터만 보내면 기업에 등록된 시/군의 IBGE 코드에 따라 자동으로 라우팅됩니다.

엔드포인트	메서드	설명
`/api/nfse/create`	POST	NFS-e 발행
`/api/nfse/cancel`	POST	NFS-e 취소
`/api/nfse/get_danfse`	POST	DANFSE 받기 (PDF)
`/api/nfse/get_xml`	POST	XML 다운로드

POST /api/nfs/company/create

NFS-e 발행을 위한 회사 등록

NFS-e 발행을 위해 회사를 등록(또는 업데이트)합니다. CNPJ가 사용자에 대해 이미 존재하는 경우, NFS-e 필드와 인증서만 업데이트됩니다. 그렇지 않으면 새 회사가 생성되고 전용 토큰이 반환됩니다. 경로 주의: /api/nfs/...("e" 없음), 다른 NFS-e 엔드포인트와 다릅니다.

필수 헤더

헤더	유형	설명
token	string	인티그레이터 B2B 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
cnpj *	string	회사 CNPJ (숫자만)
name *	string	법인명
cep *	string	우편번호 (숫자만)
address *	string	도로명
house_number *	string	주소 번호
town *	string	동네
city *	string	도시
state *	string	주 (2자리, 예: "SP")
cert_file *	string	A1 디지털 인증서(.pfx)의 URL
cert_pwd *	string	디지털 인증서 비밀번호
im *	string	시 등록 번호 (Inscrição Municipal)
codigo_municipio_nfse *	string	발행 도시의 IBGE 코드
codigo_servico_nfse *	string	기본 서비스 코드 (LC 116)
alias	string	상호
ie	string	주 등록 번호
invoice_type	string	세제 체계
unit	string	단위 / 지점
email	string	연락처 이메일
telefone	string	전화
complemento	string	주소 보충
cnae_nfse	string	기본 활동 CNAE
serie_nfse	int	NFS-e 초기 시리즈
number_nfse	int	NFS-e 초기 번호
regime_especial_tributacao	int	특별 세제 코드
optante_simples_nacional	bool	Simples Nacional 가입

* 필수 필드.

페이로드 예시

        {
          "cnpj": "43649380000100",
          "name": "EMPRESA EXEMPLO LTDA",
          "alias": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.exemplo.com/cert.pfx",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

응답

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

참고: 반환된 token은 다른 NFS-e 호출(/api/nfse/create, /cancel, /get_danfse, /get_xml)에서 사용해야 합니다. 회사가 이미 존재하는 경우 메시지는 "Empresa atualizada para NFS-e"이며 반환되는 토큰은 기존 토큰입니다.

POST /api/nfse/create

NFS-e 발행

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

        {
          "ambiente": "1",
          "id": "REF-001",
          "descricao_servico": "Desenvolvimento de sistemas",
          "valor_servico": 10000.00,
          "aliquota_iss": 2.90,
          "iss_retido": false,
          "codigo_servico": "",
          "cnae": "",
          "valor_deducoes": 0,
          "desconto_incondicionado": 0,
          "desconto_condicionado": 0,
          "valor_iss": 0,
          "valor_pis": 0,
          "valor_cofins": 0,
          "valor_inss": 0,
          "valor_ir": 0,
          "valor_csll": 0,
          "tomador": {
            "cnpj": "43649380000100",
            "cpf": "",
            "name": "EMPRESA TOMADORA LTDA",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "inscricao_municipal": "",
            "cep": "03027020",
            "endereco": "Rua Exemplo",
            "numero": "86",
            "complemento": "Andar 2",
            "bairro": "Centro",
            "city": "Sao Paulo",
            "uf": "SP",
            "codigo_municipio": "3550308"
          }
        }

주요 필드

필드	타입	설명
ambiente	string	`"1"` = 운영환경, `"2"` = 테스트환경
id	string	외부 참조 ID (선택)
descricao_servico	string	서비스 설명 (필수)
valor_servico	decimal	서비스 총 금액 (R$) (필수)
aliquota_iss	decimal	ISS 세율 (%) (예: 2.90)
iss_retido	boolean	`false` = 원천징수 없음, `true` = 지급자가 원천징수
valor_iss	decimal	ISS 값 오버라이드. 0보다 크면 자동 계산 (base_calculo × aliquota_iss ÷ 100)을 대체. 기본값: 자동 계산
codigo_servico	string	서비스 코드. 비어있으면 기업 기본값 사용
cnae	string	CNAE. 비어있으면 기업 기본값 사용
tomador	object	서비스 수령자 데이터 (필수)

지급자 필드

필드	타입	설명
cnpj	string	지급자 CNPJ (숫자만)
cpf	string	지급자 CPF (cnpj 또는 cpf 사용)
name	string	이름/회사명 (필수)
email	string	지급자 이메일
telefone	string	전화번호
cep	string	우편번호 (필수)
endereco	string	주소 (필수)
numero	string	번지 (필수)
complemento	string	보충 주소
bairro	string	지역구 (필수)
city	string	도시
uf	string	주 (2자리)
codigo_municipio	string	IBGE 시/군 코드

성공 응답

        {
          "success": true,
          "data": {
            "_id": "661234abcdef...",
            "uuid": "guid-unico",
            "status": "autorizada",
            "nfse": "48",
            "serie": 1,
            "chave": "Z685RI9C",
            "codigoVerificacao": "Z685RI9C",
            "modelo": "nfse",
            "tipoEmissao": "paulistana",
            "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
          }
        }

POST /api/nfse/cancel

NFS-e 취소

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

        {
          "chave": "Z685RI9C",
          "motivo": "Cancelamento da NFS-e por erro na emissao"
        }

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)
motivo	string	취소 사유 (필수, 최소 15자)

성공 응답

        {
          "success": true,
          "message": "Nota de servico cancelada com sucesso"
        }

POST /api/nfse/get_danfse

DANFSE 받기 (PDF)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

        {
          "chave": "Z685RI9C"
        }

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)

응답

        {
          "success": true,
          "data": {
            "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
          }
        }

참고: Paulistana (SP)의 경우 시청의 PDF 직접 URL을 반환합니다. 국가 API의 경우 base64 형식의 PDF를 반환합니다.

POST /api/nfse/get_xml

NFS-e XML 다운로드

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

        {
          "chave": "Z685RI9C"
        }

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)

응답

        {
          "success": true,
          "data": {
            "dpsXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

dpsXml: 시청/ADN에 전송된 XML 링크(OSS URL). nfseXml: 발행 결과가 포함된 반환 XML 링크. XML은 첫 요청 시 OSS에 업로드되며 URL은 캐시됩니다.

POST /api/invoice/create

보충 NFe 발행 (finalidade = 2)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

        {
          "finalidade": "2",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Complemento de preço",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Complemento de valor - Produto X",
              "ncm": "82100090",
              "count": 1,
              "unit": "UN",
              "unit_price": 5.00,
              "total_price": 5.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

Specific Fields

필드	타입	설명
finalidade	string	`"2"` for Supplementary (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

참고: The remaining fields follow the same pattern as the /api/invoice/create endpoint for regular issuance. See the NFe issuance documentation for details on all fields.

Payment: In supplementary invoices, payment is usually "90" (No Payment) since it is only a supplement of tax values.

성공 응답

        {
          "success": true,
          "data": {
            "uuid": "a1b2c3d4-e5f6-...",
            "chave": "35260312345678000195550010000004051234567890",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfe": 405,
            "serie": 1,
            "danfe": "https://storage.../danfe.pdf",
            "xml": "https://storage.../xml.xml"
          }
        }

POST /api/invoice/create

조정 NFe 발행 (finalidade = 3)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

        {
          "finalidade": "3",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Ajuste fiscal",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Ajuste fiscal - Regularização",
              "ncm": "82100090",
              "count": 1,
              "unit": "UN",
              "unit_price": 0.01,
              "total_price": 0.01,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5949"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

Specific Fields

필드	타입	설명
finalidade	string	`"3"` for Adjustment (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

Available finalidade values:

Value	설명
1	Normal (default)
2	Supplementary
3	Adjustment
4	Return

Difference between Supplementary and Adjustment:

Supplementary (2): Supplements values from the original invoice (price, tax, quantity reported lower than correct)
Adjustment (3): Tax adjustments provided by legislation (regularization, credit transfer, inventory adjustment)

edit_note CC-e — Electronic Correction Letter

The CC-e (Electronic Correction Letter) is an event linked to the NF-e that allows correcting information in an already authorized invoice, without changing tax values. Regulated by Ajuste SINIEF 01/07.

What can be corrected via CC-e:

Recipient or issuer address
Recipient company name (without changing CNPJ/CPF)
Fiscal operation code (CFOP), as long as it does not change the nature of taxes
Product description
Additional data and supplementary information

What CANNOT be corrected via CC-e:

Tax values (tax base, rate, tax amount)
Product quantity and value
Issuer or recipient CNPJ/CPF
Data that changes tax calculations

Rules:

Only invoices with authorized (Success) status can receive CC-e
Correction text must be between 15 and 1000 characters
Up to 20 CC-e can be issued for the same invoice
Each CC-e consumes 1 credit

인증

모든 CC-e 엔드포인트는 메인 API와 동일한 인증을 사용합니다:

헤더	타입	설명
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

POST /api/invoice/cce/send

정정장(CC-e) 전송

이미 승인된 NF-e의 데이터를 정정하기 위해 SEFAZ에 CC-e(이벤트 110110)를 전송합니다. 시퀀스 번호(nSeqEvento)는 자동으로 계산됩니다 — 보내지 마세요. 비재무 데이터만 정정할 수 있습니다(금액, CNPJ, IE 등은 정정할 수 없습니다).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid	string	NF-e UUID(`chave`가 없으면 필수)
chave	string	NF-e의 44자리 액세스 키(`uuid`가 없으면 필수)
correcao *	string	정정 텍스트(SEFAZ 제한: 15–1000자)

* 필수 필드. uuid 또는 chave 중 적어도 하나도 필수입니다.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
        }

응답

        {
          "success": true,
          "data": {
            "nProt": "135210000123456",
            "nSeqEvento": 1,
            "xml": "https://oss.example.com/.../cce.xml"
          }
        }

POST /api/invoice/cce/get_list

NF-e의 CC-e 목록

특정 NF-e에 발급된 모든 CC-e(정정장)를 최신순으로 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid	string	NF-e UUID(`chave`가 없으면 필수)
chave	string	NF-e의 44자리 액세스 키(`uuid`가 없으면 필수)

uuid 또는 chave 중 적어도 하나가 필수입니다.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

응답

        {
          "success": true,
          "data": {
            "items": [
              {
                "id": "65fa1b2c3d4e5f6a7b8c9d0e",
                "detail": "Corrigir nome do destinatario para Empresa XYZ LTDA",
                "nProt": "135210000123456",
                "nSeqEvento": 1,
                "date": "15/01/2024 14:30:00",
                "pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
                "xmlUrl": "https://oss.example.com/.../cce.xml"
              }
            ],
            "total": 1
          }
        }

POST /api/invoice/cce/download_pdf

CC-e PDF 다운로드

CC-e PDF URL을 반환합니다. PDF는 첫 호출 시 필요에 따라 생성되어(송장 XML + CC-e XML에서 렌더링) OSS에 저장됩니다. 이후 호출에서는 기존 URL을 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cce_id *	string	`/api/invoice/cce/get_list`의 `id` 필드로 반환되는 CC-e ID(ObjectId)

* 필수 필드.

페이로드 예시

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

응답

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce_seq1.pdf"
          }
        }

POST /api/invoice/cce/download_xml

CC-e XML 다운로드

서명된 CC-e XML URL을 반환합니다(SEFAZ에 제출된 후 이미 OSS에 저장됨).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cce_id *	string	`/api/invoice/cce/get_list`의 `id` 필드로 반환되는 CC-e ID(ObjectId)

* 필수 필드.

페이로드 예시

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

응답

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce.xml"
          }
        }

how_to_reg 수신자 표명 (Manifestação do Destinatário)

수신자 표명은 NF-e의 수신자가 자사 CNPJ 앞으로 발행된 송장에 대해 공식적으로 의사를 표명할 수 있도록 합니다. SEFAZ에서 정의한 4가지 이벤트 유형이 있으며, 각각 고유한 법적 의미를 가집니다.

이벤트 유형

코드	이름	의미	사유
210210	거래 인지	수신자가 NF-e의 존재를 인지했으나 아직 확인하거나 거부하지 않았습니다. 일반적으로 가장 먼저 보내는 이벤트로, DistDFe를 통해 전체 XML을 다운로드하기 위한 전제 조건입니다.	필수 아님
210200	거래 확인	수신자가 거래가 발생했고 상품/서비스를 수령했음을 확인합니다. 최종 이벤트로 수령을 증명합니다.	필수 아님
210220	거래 부인	수신자가 거래를 인정하지 않음을 선언합니다 (사기 의심, CNPJ 도용 등).	필수 (15-255자)
210240	거래 미실행	수신자가 거래를 인지하지만 실제로는 이루어지지 않았음을 선언합니다 (반품, 수령 거부 등).	필수 (15-255자)

순서 규칙: 인지 (210210)를 전송한 후 확인 (210200) 또는 부인 (210220) 또는 미실행 (210240)을 전송할 수 있습니다. 확인/부인/미실행은 최종 상태이며 덮어쓸 수 없습니다.

주의: cnpj 필드에 전송하는 CNPJ는 NF-e의 수신자(표명자)여야 하며, 사용하는 토큰에 연결된 시스템에 등록되어 있어야 합니다. 그렇지 않으면 SEFAZ가 "이벤트 작성자가 NF-e 수신자와 다릅니다"라는 거부를 반환합니다.

cStat 반환 코드

cStat	의미
135	✅ 이벤트가 성공적으로 등록됨
573	✅ 이벤트 중복 — 이미 등록됨 (성공으로 처리)
236	❌ 잘못된 액세스 키
491	❌ 표명이 이미 등록됨 — 최종 상태를 덮어쓸 수 없음
596	❌ 수신자 CNPJ가 제공된 값과 다름
656	❌ 부적절한 사용 (속도 제한)

POST /api/invoice/manifest

수신자 표명 이벤트 전송

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210210,
          "justificativa": "Operação reconhecida pelo destinatário"
        }

필드

필드	유형	필수	설명
chave	string	예	NF-e 액세스 키 — 44자리
cnpj	string	예	수신자 CNPJ (표명자) — 14자리, 형식 없음. 시스템에 등록되어 있어야 함
tipo_evento	int	예	이벤트 코드: `210200`, `210210`, `210220` 또는 `210240`
justificativa	string	조건부	`210220`과 `210240`에 필수. 15-255자 사이. `210200`과 `210210`에서는 무시됨

시퀀스 (nSeqEvento): 자동으로 계산됩니다. 동일한 조합 (cnpj + chave + tipo_evento)의 경우 호출마다 증가됩니다 — 따라서 중복 시 cStat: 573이 반환되며 오류 없이 저장됩니다.

성공 응답

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "67341a8f5d4e1f2a3b4c5d6e",
            "chave": "35260514200166000187550010000000011000000018",
            "cnpj": "14200166000187",
            "tipo_evento": 210210,
            "desc_evento": "Ciencia da Operacao",
            "nProt": "135260000123456",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a NF-e",
            "nSeqEvento": 1,
            "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
          }
        }

응답 필드

필드	유형	설명
id	string	표명 레코드의 내부 ObjectId (`/get_xml`에서 사용)
chave	string	표명된 NF-e의 액세스 키
cnpj	string	표명한 수신자 CNPJ
tipo_evento	int	전송된 이벤트 코드 (210200/210210/210220/210240)
desc_evento	string	이벤트 텍스트 설명 (SEFAZ 원문)
nProt	string	SEFAZ 프로토콜 번호 — 이벤트 영수증
cStat	int	SEFAZ 상태 코드. `135` = 등록됨, `573` = 중복 (또한 수락됨)
xMotivo	string	SEFAZ 설명 메시지
nSeqEvento	int	자동으로 할당된 이벤트 시퀀스
xml_url	string	OSS에 저장된 procEvento XML (서명 및 프로토콜 포함)의 공개 URL

예시 — 사유와 함께 부인 (210220)

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210220,
          "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
        }

POST /api/invoice/manifest/list

전송된 표명 목록 (이력)

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "cnpj": "14200166000187",
          "chave": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

필드

필드	유형	필수	설명
cnpj	string	아니오	수신자 CNPJ로 필터링. 생략 시 사용자의 모든 CNPJ에서 검색
chave	string	아니오	특정 NF-e 키 (44자리)로 필터링
start_create_time	string/long	아니오	시작 날짜. 다음 형식 허용: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` 또는 Unix 타임스탬프 (초). 날짜만 있을 경우 00:00:00 UTC로 간주
end_create_time	string/long	아니오	종료 날짜. 같은 형식. 날짜만 있을 경우 23:59:59.999 UTC로 간주
page	int	아니오	페이지 번호 (기본 `1`)
page_size	int	아니오	페이지당 항목 수 (기본 `20`, 최대 `100`)

성공 응답

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 2,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "67341a8f5d4e1f2a3b4c5d6e",
                "chave": "35260514200166000187550010000000011000000018",
                "cnpj": "14200166000187",
                "tipo_evento": 210210,
                "desc_evento": "Ciencia da Operacao",
                "justificativa": "Operação reconhecida pelo destinatário",
                "nProt": "135260000123456",
                "nSeqEvento": 1,
                "cStat": 135,
                "xMotivo": "Evento registrado e vinculado a NF-e",
                "xml_url": "https://storage.../...210210_1.xml",
                "create": "2026-05-13 14:25:33"
              }
            ]
          }
        }

응답 필드

필드	유형	설명
total	int	필터 조건과 일치하는 레코드 총 개수 (페이지네이션 무관)
page	int	반환된 현재 페이지
page_size	int	반환된 페이지 크기
list[].id	string	레코드의 내부 ObjectId
list[].chave	string	표명된 NF-e의 액세스 키
list[].cnpj	string	표명한 수신자 CNPJ
list[].tipo_evento	int	이벤트 코드 (210200/210210/210220/210240)
list[].desc_evento	string	이벤트 텍스트 설명
list[].justificativa	string	전송된 사유 (210220/210240에서만 채워짐)
list[].nProt	string	이벤트의 SEFAZ 프로토콜 번호
list[].nSeqEvento	int	이벤트 시퀀스
list[].cStat	int	SEFAZ 상태 코드
list[].xMotivo	string	SEFAZ 설명 메시지
list[].xml_url	string	OSS의 procEvento XML 공개 URL
list[].create	string	레코드의 UTC 타임스탬프 (형식 `yyyy-MM-dd HH:mm:ss`)

정렬: 레코드는 최신순(생성일 내림차순)으로 반환됩니다.

POST /api/invoice/manifest/get_xml

특정 표명의 XML URL 가져오기

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "id": "67341a8f5d4e1f2a3b4c5d6e"
        }

필드

필드	유형	필수	설명
id	string	예	표명의 ObjectId — `/manifest` 또는 `/manifest/list`에서 반환됨

성공 응답

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "67341a8f5d4e1f2a3b4c5d6e",
            "chave": "35260514200166000187550010000000011000000018",
            "tipo_evento": 210210,
            "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
          }
        }

일반적인 오류

메시지	원인
id inválido	값이 유효한 ObjectId가 아님
manifestação não encontrada	ObjectId는 존재하지만 토큰의 사용자에 속하지 않거나 삭제됨

cloud_download DistDFe 캡처 — 수신 NFe

SEFAZ (국가 환경)의 NFeDistribuicaoDFe 서비스를 통해 자사 CNPJ로 도착한 NFe와 이벤트를 조회하고 다운로드할 수 있습니다. 캡처는 NSU(고유 순차 번호)별 증분 방식으로 — 각 호출은 아직 캡처되지 않은 항목만 다운로드합니다.

반환되는 문서 유형

doc_type	설명	내용
resNFe	NFe 요약	기본 메타데이터 (키, 금액, 발행자, 상태). 인지 이벤트가 전송되기 전에 도착 — 상품/세금이 포함되지 않음
procNFe	전체 승인된 NFe	완전한 NF-e XML (상품, 세금, 운송 등 포함). 수신자가 해당 키에 대해 인지 (210210)를 전송한 후에만 사용 가능
resEvento	이벤트 요약	이벤트 메타데이터 (키, 유형, 시퀀스, 사유)
procEvento	전체 이벤트	완전한 이벤트 XML (CC-e, 취소, 다른 수신자의 표명 등)

권장 워크플로:

/received/sync 호출 — 모든 새 문서 다운로드
/received/list에서 doc_type: "resNFe"로 필터링하여 인지하지 않은 송장 확인
관심있는 각 키에 대해 /invoice/manifest를 tipo_evento: 210210으로 호출
/received/sync 다시 호출 — 이제 SEFAZ가 표명된 키의 procNFe(전체 XML) 반환
/received/get_xml로 XML URL을 가져와 처리

SEFAZ 속도 제한: SEFAZ는 CNPJ당 시간당 최대 1회의 DistDFe 호출을 허용합니다. 초과 시 cStat: 656(부적절한 사용)이 반환됩니다. 검증 환경에서는 더 관대한 규칙이 적용됩니다.

DistDFe 반환 cStat 코드

cStat	의미
137	✅ 문서 없음 (정상 루프 종료)
138	✅ 문서 발견 — 루프 계속
656	❌ 부적절한 사용 — 1시간 대기 후 재시도
252	❌ 제공된 환경과 다름 (프로덕션 vs 검증)
280	❌ 인증서 만료 또는 무효

POST /api/invoice/received/sync

동기화 — SEFAZ에서 DistDFe를 통해 새로운 NFe/이벤트 다운로드

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "cnpj": "26638419000167",
          "max_iterations": 50
        }

필드

필드	유형	필수	설명
cnpj	string	예	수신자 회사 CNPJ — 14자리, 형식 없음. 토큰에 연결된 시스템에 등록되어 있어야 함
max_iterations	int	아니오	실행당 최대 SEFAZ 호출 수. 각 호출은 최대 50개 문서 다운로드. 기본 `50` (≈2,500개 문서), 최대 `200`

작동 방식:

(uid + cnpj)에 대해 저장된 최신 ultNSU 읽기
cStat ≠ 138 또는 max_iterations에 도달할 때까지 SEFAZ 호출 루프
반환된 XML (gzip) 압축 해제
각 문서를 w_invoice_received에 저장하고 XML을 OSS에 업로드
w_invoice_received_sync의 ultNSU와 maxNSU 업데이트
(uid + cnpj + nsu)로 중복 제거 — 반복 호출 시 중복되지 않음

성공 응답

        {
          "success": true,
          "message": "data",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "initial_nsu": 0,
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "iterations": 8,
            "last_cstat": 137,
            "last_motivo": "Nenhum documento localizado",
            "stats": {
              "resNFe": 3,
              "procNFe": 4,
              "resEvento": 336,
              "procEvento": 5,
              "skipped": 0
            }
          }
        }

응답 필드

필드	유형	설명
cnpj	string	조회된 수신자 CNPJ
uf	string	조회에 사용된 수신자 주(州) 코드
initial_nsu	long	시작 NSU — 이 실행 전에 처리된 마지막 NSU
ult_nsu	long	동기화 후 새로운 마지막 NSU
max_nsu	long	조회 시점에 SEFAZ AN에서 사용 가능한 최대 NSU
pending	long	여전히 보류 중인 문서 (`max_nsu - ult_nsu`). > 0이면 `/sync`를 다시 호출하여 나머지 다운로드
iterations	int	이 실행에서 수행된 SEFAZ 호출 수
last_cstat	int	SEFAZ가 반환한 마지막 cStat. `137`은 정상 종료, `656`은 속도 제한
last_motivo	string	SEFAZ 마지막 반환 메시지
stats.resNFe	int	이 실행에서 다운로드한 NFe 요약 수
stats.procNFe	int	다운로드한 전체 NFe 수
stats.resEvento	int	다운로드한 이벤트 요약 수
stats.procEvento	int	다운로드한 전체 이벤트 수
stats.skipped	int	건너뛴 문서 (중복 또는 개별 파싱 오류)

초기 볼륨: 한 번도 동기화하지 않은 회사는 수백에서 수천 개의 과거 문서가 있을 수 있습니다. 첫 실행은 시간이 더 걸리며 max_iterations로 중단될 수 있습니다. 응답의 pending을 확인하고 — > 0이면 다시 호출 (속도 제한 준수).

POST /api/invoice/received/list

캡처된 문서 (NFe와 이벤트) 목록

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "cnpj": "26638419000167",
          "doc_type": "resNFe",
          "chave": "",
          "emitente_cnpj": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

필드

필드	유형	필수	설명
cnpj	string	아니오	수신자 CNPJ(자사 CNPJ)로 필터링. 생략 시 사용자의 모든 항목
doc_type	string	아니오	문서 유형별 필터: `resNFe`, `procNFe`, `resEvento` 또는 `procEvento`
chave	string	아니오	액세스 키 (44자리)로 필터링
emitente_cnpj	string	아니오	NF-e 발행자 CNPJ (공급업체)로 필터링
start_create_time	string/long	아니오	시작 날짜. `"dd/MM/yyyy"`, ISO 또는 Unix 타임스탬프 허용
end_create_time	string/long	아니오	종료 날짜. 같은 형식
page	int	아니오	페이지 번호 (기본 `1`)
page_size	int	아니오	페이지당 항목 수 (기본 `20`, 최대 `100`)

성공 응답

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 3,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "6a04a70d3201b5a62f3ac2f8",
                "nsu": 2318,
                "doc_type": "resNFe",
                "schema": "resNFe_v1.01.xsd",
                "chave": "35260563845920000120550020000085471156822656",
                "cnpj_destinatario": "26638419000167",
                "emitente_cnpj": "63845920000120",
                "emitente_nome": "MEGA ONLINE LTDA",
                "valor": 1.00,
                "dh_emi": "2026-05-13 14:05:35",
                "serie": 0,
                "number": 0,
                "tp_nf": 1,
                "c_sit_nfe": 3,
                "tp_evento": 0,
                "desc_evento": "",
                "n_seq_evento": 0,
                "dh_evento": null,
                "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
                "create": "2026-05-13 16:30:05"
              }
            ]
          }
        }

응답 필드

필드	유형	설명
total	int	필터 조건과 일치하는 레코드 총 개수
page	int	현재 페이지
page_size	int	페이지 크기
list[].id	string	내부 ObjectId (`/received/get_xml`에서 사용)
list[].nsu	long	SEFAZ가 이 문서에 할당한 NSU
list[].doc_type	string	문서 유형: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	문서 스키마 (예 `resNFe_v1.01.xsd`)
list[].chave	string	NF-e 액세스 키 (44자리)
list[].cnpj_destinatario	string	수신자 CNPJ (자사 CNPJ)
list[].emitente_cnpj	string	NF-e 발행자 CNPJ (공급업체)
list[].emitente_nome	string	발행자 회사명
list[].valor	decimal	NF-e 총액 (`vNF`)
list[].dh_emi	string	NF-e 발행 일시
list[].serie	int	NF-e 시리즈 (`procNFe`에서만 채워짐)
list[].number	long	NF-e 번호 (`procNFe`에서만 채워짐)
list[].tp_nf	int	거래 유형: `0`=입고, `1`=출고 (발행자 관점)
list[].c_sit_nfe	int	NF-e 상태 (`resNFe` 내): `1`=승인, `2`=거부, `3`=취소
list[].tp_evento	int	이벤트 코드 (`resEvento`/`procEvento` 내). 예: `110110`=CC-e, `110111`=취소, `210210`=인지
list[].desc_evento	string	이벤트 텍스트 설명
list[].n_seq_evento	int	이벤트 시퀀스
list[].dh_evento	string	이벤트 일시 (이벤트만)
list[].xml_url	string	OSS의 문서 XML 공개 URL
list[].create	string	캡처 UTC 타임스탬프

정렬: 레코드는 NSU 내림차순(최신 항목 우선)으로 반환됩니다.

POST /api/invoice/received/get_xml

특정 수신 문서의 XML URL 가져오기

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "id": "6a04a70d3201b5a62f3ac2f8"
        }

필드

필드	유형	필수	설명
id	string	예	문서의 ObjectId — `/received/list`에서 반환됨

성공 응답

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "6a04a70d3201b5a62f3ac2f8",
            "nsu": 2318,
            "doc_type": "resNFe",
            "chave": "35260563845920000120550020000085471156822656",
            "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
          }
        }

반환되는 XML 정보:

resNFe — XML은 요약일 뿐, 상품/세금이 포함되지 않습니다. 인지 전 감사/선별용
procNFe — 발행 시 생성된 것과 동일한 전체 서명 XML. 클라이언트의 ERP에 가져오기 준비됨
procEvento — 서명 및 프로토콜이 포함된 전체 이벤트 XML

일반적인 오류

메시지	원인
id inválido	값이 유효한 ObjectId가 아님
documento recebido não encontrado	ObjectId는 존재하지만 토큰의 사용자에 속하지 않음

POST /api/invoice/received/get_sync_status

현재 DistDFe 동기화 상태 확인 (SEFAZ 호출 안 함)

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

        {
          "cnpj": "26638419000167"
        }

필드

필드	유형	필수	설명
cnpj	string	예	수신자 회사 CNPJ — 14자리, 형식 없음

응답 — 이미 동기화된 회사

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "last_sync": "2026-05-13 16:30:05"
          }
        }

응답 — 동기화되지 않은 회사

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "ult_nsu": 0,
            "max_nsu": 0,
            "pending": 0,
            "last_sync": null
          }
        }

응답 필드

필드	유형	설명
cnpj	string	조회된 CNPJ
uf	string	마지막 동기화에서 사용된 수신자 주(州) 코드 (동기화하지 않은 경우 없음)
ult_nsu	long	마지막으로 처리된 NSU. `0` = 동기화하지 않음
max_nsu	long	마지막 동기화 시 SEFAZ에서 사용 가능한 최대 NSU
pending	long	보류 중인 문서 (`max_nsu - ult_nsu`). > 0이면 SEFAZ에 새 문서가 있음
last_sync	string	마지막 성공한 동기화의 UTC 일시. 동기화하지 않은 경우 `null`

일반적인 사용: /received/sync를 호출하기 전에 이 엔드포인트를 호출하여 SEFAZ 호출 필요성을 판단합니다. 이 엔드포인트는 SEFAZ 속도 제한을 사용하지 않으며 — 로컬 MongoDB 상태만 읽습니다.

GET /api/nfse/get_list

NFS-e 목록(페이지네이션)

회사의 NFS-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링. 값: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* 필수 필드.

호출 예시

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping MDF-e — 전자 세무 문서 매니페스트

MDF-e API(모델 58, PL-MDFe 3.00 레이아웃)는 운송 매니페스트 발행, 조회, 취소 및 종료를 지원합니다. MDF-e는 운송 작업과 연결된 NF-e 및/또는 CT-e를 집계하며 도로, 항공, 수상, 철도의 4가지 모달을 지원합니다. 모든 운영 정보(운전자, 차량, 계약자, CIOT, 통행료 바우처, 결제)는 /create 본문에 포함됩니다 — 발행 후 추가/변경 이벤트는 없습니다.

엔드포인트	메소드	설명
`/api/mdfe/create`	POST	MDF-e 발행
`/api/mdfe/consult`	POST	MDF-e 상태 조회
`/api/mdfe/cancel`	POST	MDF-e 취소(승인 후 24시간 이내)
`/api/mdfe/close`	POST	MDF-e 종료(여행 종료 후)

POST /api/mdfe/create

MDF-e 발행

전송된 본문에서 MDF-e를 발행합니다. cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc 필드는 서버에서 자동으로 계산됩니다. serie와 nMDF는 선택 사항입니다 — 생략하거나 0으로 보내면 자동으로 할당되고, 요청에 값을 보내면 그대로 적용됩니다(예: SEFAZ 중복 발생 후 번호를 건너뛸 때 유용). 클라이언트는 비즈니스 필드만 전송합니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body — 루트

필드	유형	설명
ide *	object	MDF-e 식별
emit *	object	발행자 데이터
infModal *	object	모달 정보(4개 중 하나만: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	연결된 세무 문서
tot *	object	화물 합계
prodPred	object	주요 화물 제품
seg	array	보험 정보
lacres	array	MDF-e 봉인
autXML	array	XML 액세스 권한 있는 CNPJ/CPF
infAdic	object	추가 정보(세무 당국 및 납세자)
infRespTec	object	기술 책임자(CNPJ, 연락처, 이메일 등)

ide — 식별

필드	유형	설명
tpAmb *	int	환경: `1`=운영, `2`=호몰로게이션
tpEmit *	int	발행자 유형: `1`=운송업체, `2`=자체 화물, `3`=운송 서비스 제공자
modal *	string	모달: `"1"`=도로, `"2"`=항공, `"3"`=수상, `"4"`=철도
UFIni *	string	여행 시작 UF(2자)
UFFim *	string	여행 종료 UF
infMunCarrega[] *	array	적재 시: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	경로의 UF: `[{ UFPer }]`
tpTransp	string	운송업체 유형(도로)
dhIniViagem	string	여행 시작 일시(ISO 8601)
indCanalVerde	string	그린 채널 표시
indCarregaPosterior	string	후속 적재 표시
serie	int	MDF-e 시리즈(액세스 키의 3자리). 선택 사항 — 생략하거나 `0`이면 자동 할당됨(회사의 MDF-e 시리즈), 값을 보내면 그대로 적용됨
nMDF	int	MDF-e 번호(액세스 키를 구성). 선택 사항 — 생략하거나 `0`이면 서버에서 자동 증가됨, 값을 보내면 그대로 적용됨(예: 중복 발생 후 번호를 건너뛸 때 유용)

emit — 발행자

필드	유형	설명
CNPJ ⚠	string	발행자 CNPJ(14자리)
CPF ⚠	string	발행자 CPF(11자리)
IE	string	주 등록 번호
xNome *	string	법인명
xFant	string	상호
enderEmit	object	주소: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — 도로 모달(modal="1")

필드	유형	설명
rodo.veicTracao *	object	견인 차량: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	운전자: `[{ xNome, CPF }]` — 최소 1
rodo.veicReboque[]	array	트레일러 차량(운전자 없는 veicTracao와 동일한 구조)
rodo.infANTT	object	ANTT 정보: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	항구 예약 코드
rodo.lacRodo[]	array	모달 봉인: `[{ nLacre }]`

infModal — 항공 모달(modal="2")

필드	유형	설명
aereo.nac *	string	항공기 국적 마크
aereo.matr *	string	항공기 등록
aereo.nVoo *	string	비행 번호
aereo.cAerEmb *	string	탑승 공항 IATA 코드
aereo.cAerDes *	string	목적지 공항 IATA 코드
aereo.dVoo *	string	비행 날짜(YYYY-MM-DD)

infModal — 수상 모달(modal="3")

필드	유형	설명
aquav.irin *	string	선박 IRIN
aquav.tpEmb *	string	선박 유형(2자리). Zeus 내부 `byte` 잘림을 피하기 위해 ≥ 10 값 사용(예: `"10"`, `"11"`)
aquav.cEmbar *	string	선박 코드
aquav.xEmbar *	string	선박 이름
aquav.nViag *	string	항해 번호. 0으로 시작할 수 없음(스키마 검증) — `"1"`, `"100"` 등.
aquav.cPrtEmb *	string	탑승 항구 코드
aquav.cPrtDest *	string	목적 항구 코드
aquav.prtTrans	string	환적 항구
aquav.tpNav	string	항해 유형
aquav.infTermCarreg[]	array	적재 터미널: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	하역 터미널
aquav.infEmbComb[]	array	선단 선박: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	빈 화물 단위
aquav.infUnidTranspVazia[]	array	빈 운송 단위

infModal — 철도 모달(modal="4")

필드	유형	설명
ferrov.trem *	object	기차 데이터: `{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	화차: `[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — 최소 1. Zeus/SEFAZ 제약: `serie`는 정확히 3자리(100+ 사용, 예: `"100"`); `nVag`는 숫자만(내부적으로 `long`, 예: `"100001"`); `nSeq`는 선택적 1-3자리.

infDoc — 연결된 문서

필드	유형	설명
infMunDescarga[] *	array	하역 시 — 최소 1
infMunDescarga[].cMunDescarga *	string	시 IBGE 코드
infMunDescarga[].xMunDescarga *	string	시 이름
infMunDescarga[].infNFe[]	array	연결된 NF-e: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	연결된 CT-e
infMunDescarga[].infMDFeTransp[]	array	운송 MDF-e(하청)

prodPred — 주요 제품

필드	유형	설명
tpCarga *	string	화물 유형: `"01"`=고체 벌크, `"02"`=액체 벌크, `"03"`=냉장, `"04"`=컨테이너, `"05"`=일반 화물, `"06"`=신벌크, `"07"`=위험물, `"08"`=가압 벌크
xProd *	string	주요 제품 설명
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	로트: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — 합계

필드	유형	설명
vCarga *	decimal	화물 총 가치(> 0)
cUnid *	string	단위 코드: `"01"`=KG, `"02"`=TON
qCarga *	decimal	화물 총 수량(> 0)
qCTe	int	연결된 CT-e 수
qNFe	int	연결된 NF-e 수
qMDFe	int	연결된 MDF-e 수

* 필수 필드. ⚠ CNPJ 또는 CPF 중 하나는 필수입니다.

간소화된 예시 — 도로 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "veicTracao": {
                "placa": "ABC1D23",
                "tara": 8000,
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" }
                ],
                "tpRod": "01",
                "tpCar": "01"
              }
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          }
        }

간소화된 예시 — 항공 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "2",
            "UFIni": "SP",
            "UFFim": "RJ",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV AEROPORTO",
              "nro": "5000",
              "xBairro": "CUMBICA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aereo": {
              "nac": "PT",
              "matr": "ABC1234",
              "nVoo": "AB1234",
              "cAerEmb": "GRU",
              "cAerDes": "GIG",
              "dVoo": "2026-05-21"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3304557",
                "xMunDescarga": "Rio de Janeiro",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 25000.00,
            "cUnid": "01",
            "qCarga": 500.00
          }
        }

간소화된 예시 — 수상 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "3",
            "UFIni": "SP",
            "UFFim": "PA",
            "infMunCarrega": [
              { "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "NAVEGACAO EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV PORTUARIA",
              "nro": "200",
              "xBairro": "PORTO",
              "cMun": "3548500",
              "xMun": "SANTOS",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aquav": {
              "irin": "1234567",
              "tpEmb": "10",
              "cEmbar": "1234",
              "xEmbar": "EMBARCACAO EXEMPLO",
              "nViag": "1",
              "cPrtEmb": "BRSSZ",
              "cPrtDest": "BRBEL"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "1501402",
                "xMunDescarga": "Belém",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "GRAOS DE SOJA"
          },
          "tot": {
            "vCarga": 500000.00,
            "cUnid": "02",
            "qCarga": 50.00
          }
        }

간소화된 예시 — 철도 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "4",
            "UFIni": "MG",
            "UFFim": "SP",
            "infMunCarrega": [
              { "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "FERROVIA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV FERROVIARIA",
              "nro": "300",
              "xBairro": "INDUSTRIAL",
              "cMun": "3106200",
              "xMun": "BELO HORIZONTE",
              "UF": "MG"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "ferrov": {
              "trem": {
                "xPref": "F123",
                "dhTrem": "2026-05-21T08:00:00-03:00",
                "xOri": "BELO HORIZONTE",
                "xDest": "SANTOS",
                "qVag": 2
              },
              "vag": [
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "100",
                  "nVag": "100001",
                  "nSeq": "1",
                  "TU": 28.000
                },
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "101",
                  "nVag": "100002",
                  "nSeq": "2",
                  "TU": 28.000
                }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3548500",
                "xMunDescarga": "Santos",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "MINERIO DE FERRO"
          },
          "tot": {
            "vCarga": 800000.00,
            "cUnid": "02",
            "qCarga": 56.00
          }
        }

완전한 예시(모든 필드) — 도로 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "tpTransp": "1",
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ],
            "dhIniViagem": "2026-05-21T08:00:00-03:00",
            "indCanalVerde": "1",
            "indCarregaPosterior": "0"
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "xFant": "Exemplo Transportes",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "GALPAO A",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP",
              "fone": "1133334444",
              "email": "contato@exemplo.com"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "infANTT": {
                "RNTRC": "12345678",
                "infCIOT": [
                  { "CIOT": "1234567890", "CNPJ": "12345678000199" }
                ],
                "valePed": {
                  "categCombVeic": "01",
                  "disp": [
                    {
                      "CNPJForn": "98765432000111",
                      "CNPJPg": "12345678000199",
                      "nCompra": "VP001",
                      "vValePed": 250.00,
                      "tpValePed": "01"
                    }
                  ]
                },
                "infContratante": [
                  {
                    "xNome": "EMPRESA CONTRATANTE LTDA",
                    "CNPJ": "11222333000144"
                  }
                ],
                "infPag": [
                  {
                    "xNome": "João da Silva",
                    "CPF": "12345678909",
                    "Comp": [
                      { "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
                    ],
                    "vContrato": 5000.00,
                    "indAltoDesemp": "1",
                    "indPag": "0",
                    "infBanc": {
                      "codBanco": "001",
                      "codAgencia": "1234",
                      "PIX": "12345678909"
                    }
                  }
                ]
              },
              "veicTracao": {
                "cInt": "VT001",
                "placa": "ABC1D23",
                "RENAVAM": "12345678901",
                "tara": 8000,
                "capKG": 25000,
                "capM3": 80,
                "prop": {
                  "CNPJ": "12345678000199",
                  "RNTRC": "12345678",
                  "xNome": "TRANSPORTADORA EXEMPLO LTDA",
                  "IE": "123456789012",
                  "UF": "SP",
                  "tpProp": "0"
                },
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" },
                  { "xNome": "Maria Souza", "CPF": "98765432100" }
                ],
                "tpRod": "01",
                "tpCar": "01",
                "UF": "SP"
              },
              "veicReboque": [
                {
                  "cInt": "VR001",
                  "placa": "DEF4G56",
                  "RENAVAM": "98765432109",
                  "tara": 3500,
                  "capKG": 30000,
                  "capM3": 90,
                  "tpCar": "02",
                  "UF": "SP"
                }
              ],
              "lacRodo": [
                { "nLacre": "LACRE001" },
                { "nLacre": "LACRE002" }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  {
                    "chNFe": "35260512345678000199550010000000011000000018",
                    "SegCodBarras": "",
                    "indReentrega": "0",
                    "infUnidTransp": [
                      {
                        "tpUnidTransp": "1",
                        "idUnidTransp": "UT001",
                        "qtdRat": 100.000,
                        "lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
                        "infUnidCarga": [
                          {
                            "tpUnidCarga": "1",
                            "idUnidCarga": "UC001",
                            "qtdRat": 100.000,
                            "lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
                          }
                        ]
                      }
                    ],
                    "peri": []
                  }
                ]
              }
            ]
          },
          "seg": [
            {
              "infResp": {
                "respSeg": "1",
                "CNPJ": "12345678000199"
              },
              "infSeg": {
                "xSeg": "SEGURADORA EXEMPLO SA",
                "CNPJ": "55666777000188"
              },
              "nApol": "APOL-2026-001",
              "nAver": ["AV001", "AV002"]
            }
          ],
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL",
            "cEAN": "7891234567890",
            "NCM": "84713012",
            "infLotacao": {
              "infLocalCarrega": {
                "CEP": "01001000",
                "latitude": "-23.5505",
                "longitude": "-46.6333"
              },
              "infLocalDescarrega": {
                "CEP": "29100000",
                "latitude": "-20.3297",
                "longitude": "-40.2925"
              }
            }
          },
          "tot": {
            "qCTe": 0,
            "qNFe": 1,
            "qMDFe": 0,
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          },
          "lacres": [
            { "nLacre": "LACRE-GERAL-001" }
          ],
          "autXML": [
            { "CNPJ": "11222333000144" }
          ],
          "infAdic": {
            "infAdFisco": "Documento emitido em conformidade com a legislação vigente",
            "infCpl": "Transporte com escolta armada"
          },
          "infRespTec": {
            "CNPJ": "12345678000199",
            "xContato": "Suporte Técnico",
            "email": "suporte@exemplo.com",
            "fone": "1133334444"
          }
        }

성공 응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

MDF-e 상태 조회

액세스 키를 사용해 SEFAZ에서 직접 MDF-e 상태를 조회합니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 100,
            "xMotivo": "Autorizado o uso do MDF-e",
            "protocolo": "135260000123456",
            "dhRecbto": "2026-05-21T10:30:00-03:00",
            "encerrado": false,
            "cancelado": false
          }
        }

POST /api/mdfe/cancel

MDF-e 취소

승인된 MDF-e를 취소합니다. 창: 승인 후 최대 24시간. MDF-e가 이미 종료된 경우 허용되지 않습니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)
xJust *	string	취소 사유(SEFAZ 요구 사항에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123457",
            "dhRegEvento": "2026-05-21T11:00:00-03:00"
          }
        }

POST /api/mdfe/close

MDF-e 종료

여행이 끝나면 MDF-e를 종료합니다. 종료 후에는 더 이상 취소할 수 없습니다. dtEnc, cUF, cMun 필드는 선택 사항이며, 생략되면 시스템이 원본 MDF-e에서 추론합니다(현재 날짜, 발행자의 UF 및 시).

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)
dtEnc	string	종료일(YYYY-MM-DD). 기본값: 현재 날짜
cUF	int	종료가 발생한 UF의 IBGE 코드. 기본값: 발행자의 UF
cMun	string	시 IBGE 코드 onde ocorreu o encerramento. Default: município do emitente

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "dtEnc": "2026-05-22",
          "cUF": 32,
          "cMun": "3205200"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123458",
            "dhRegEvento": "2026-05-22T18:00:00-03:00"
          }
        }

GET /api/mdfe/get_list

MDF-e 목록(페이지네이션)

회사의 MDF-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링. 값: `"Success"`(승인됨), `"Canceled"`(취소됨), `"Voided"`(종료됨), `"Processing"`(처리 중), `"Failed"`(실패), `"Unknown"`(알 수 없음)

* 필수 필드.

호출 예시

GET /api/mdfe/get_list?page=1&page_size=20&status=Success

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190580010000000011000000015",
                "serie": 1,
                "number": 1,
                "modal": "1",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

inventory_2 DC-e — 전자 내용물 신고서 (Declaração de Conteúdo Eletrônica)

DC-e API(모델 99, 레이아웃 1.00)는 전자 내용물 신고서의 발행, 조회, 취소 및 PDF(DACE) 가져오기를 지원합니다. DC-e는 세금계산서 발행 의무가 없는 경우 — 예를 들어 ICMS 비납세자가 관련된 운송 — 재화 또는 상품의 운송을 보증하는 세금 문서입니다. 발행자는 항상 법인(CNPJ)이며, 수신자는 법인(CNPJ) 또는 개인(CPF)일 수 있습니다. 비즈니스 데이터는 /create 본문에 들어갑니다. 액세스 키의 기술 필드(cDC, cDV, cUF, dhEmi, mod)는 서버에서 자동으로 계산됩니다.

Endpoint	메서드	설명
`/api/dce/create`	POST	DC-e 발행
`/api/dce/consult`	POST	DC-e 상태 조회
`/api/dce/cancel`	POST	승인된 DC-e 취소
`/api/dce/pdf`	POST	DC-e의 DACE(PDF) 가져오기

DC-e는 발행자 UF의 인가 기관으로 라우팅됩니다. ide.cUF 필드는 emit.enderEmit.UF에 입력된 UF와 일치해야 합니다 — 불일치 시 SEFAZ는 cStat=220으로 거부합니다. 생략하면 cUF는 해당 UF에서 도출됩니다.

POST /api/dce/create

DC-e 발행

전송된 본문으로 DC-e를 발행합니다. 클라이언트는 비즈니스 데이터만 전송합니다. 액세스 키의 기술 식별 필드는 서버에서 계산합니다(ide 테이블 아래 참고 사항 참조). 크레딧 차감은 운영 환경(tpAmb=1)에서 DC-e가 승인될 때만 발생합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	초 단위 Unix 타임스탬프 (5분 윈도우)

Body — 최상위 필드

필드	타입	설명
ide *	object	DC-e 식별 정보
emit *	object	발행자/발송인 데이터 (CNPJ, 또는 Marketplace를 통한 CPF — 아래 참조)
dest *	object	수신자 데이터
det *	array	신고 품목/재화 — 최소 1개
total *	object	신고서 합계
transp	object	운송 데이터
marketplace	object	마켓플레이스 데이터 (`ide.tpEmit=1`일 때만)
fisco	object	세무 기관 데이터 (`ide.tpEmit=0`일 때만)
autXML	array	XML 접근이 허가된 CNPJ/CPF
infAdic	object	추가 정보

요청의 필수 필드: ide.tpAmb; emit.CNPJ(14자리) 또는 emit.CPF(11자리, Marketplace를 통한 개인 발송인 — emit의 참고 참조), emit.xNome 및 emit.enderEmit(xLgr, nro, xBairro, cMun, xMun, CEP 8자리, UF); CNPJ 또는 CPF가 있는 dest, dest.xNome 및 dest.enderDest(동일한 주소 필드); xProd, NCM(2 또는 8자리), qCom > 0 및 vProd > 0을 갖는 det 항목 최소 1개; 그리고 total.vDC > 0. 그 외 모든 필드는 선택 사항입니다.

ide — 식별 정보

필드	타입	설명
tpAmb *	int	환경: `1`=운영, `2`=테스트. `ide`에서 유일하게 실제로 필수인 필드입니다.
tpEmit	int	발행자 유형: `0`=세무 기관 애플리케이션, `1`=마켓플레이스, `2`=자체 발행자. 선택 사항 — 기본값: `2`
cUF	int	발행자 UF의 IBGE 코드(2자리). 선택 사항 — 생략 시 `emit.enderEmit.UF`에서 도출됨. 전송 시 해당 UF와 일치해야 함(불일치 시 SEFAZ가 `cStat=220`으로 거부함)
serie	int	세금 문서의 시리즈(액세스 키의 3자리) — DC-e의 번호 집합을 식별함. 선택 사항 — 기본값: 회사에 등록된 DC-e 시리즈
nDC	long	DC-e의 일련번호(액세스 키를 구성). 선택 사항 — 생략하거나 `0`이면 서버에서 자동 증가됨
nSiteAutoriz	int	DC-e를 처리한 인가 사이트 식별자(액세스 키의 1자리). 일반적으로 `0`(기본 사이트). 선택 사항 — 기본값: `0`
tpEmis	int	발행 방식: `1`=정상, `9`=비상. 선택 사항 — 기본값: `1`

서버에서 자동으로 채워짐 — 전송할 필요 없음: mod(99로 고정) 및 cDV(키의 검증 자릿수)는 항상 서버에서 설정됩니다. cDC(6자리 숫자 코드), dhEmi(발행 일시) 및 verProc(프로세스 버전)는 생략 시 생성됩니다. 위 테이블의 serie, nDC 및 cUF 필드도 생략 시 자동으로 채워집니다.

emit — 발행자 / 발송인

필드	타입	설명
CNPJ ⚠	string	발행자 CNPJ(14자리). 생략 시 토큰 회사의 CNPJ로 채워짐
CPF ⚠	string	개인 발송인의 CPF(11자리). Marketplace를 통한 발행에서만 허용됨 — 아래 참고 참조
xNome *	string	발행자/발송인의 이름 또는 법인명
enderEmit *	object	발행자 주소(아래 구조 참조)

개인 발송인(CPF): SEFAZ 규칙에 따라 CPF는 자체 발행자가 될 수 없습니다(tpEmit=2는 CNPJ 필수). CPF를 발송인으로 발행하려면 emit.CPF만 전송하면 됩니다(emit.CNPJ 없이). 서버가 자동으로 tpEmit=1(Marketplace)을 설정하고, 액세스 키의 인가 발행자로 귀사의 CNPJ(토큰 회사)를 사용하며, marketplace 블록을 회사 데이터로 채웁니다. 입력한 CPF는 emit에 발송인으로 표시됩니다.

dest — 수신자

필드	타입	설명
CNPJ ⚠	string	수신자 CNPJ(14자리)
CPF ⚠	string	수신자 CPF(11자리)
xNome *	string	수신자의 이름 또는 법인명
enderDest *	object	수신자 주소(아래 구조 참조)

enderEmit / enderDest — 주소

필드	타입	설명
xLgr *	string	도로명
nro *	string	번지
xCpl	string	상세 주소
xBairro *	string	구/동
cMun *	long	자치단체 IBGE 코드(7자리)
xMun *	string	자치단체명
CEP *	string	우편번호(8자리)
UF *	string	UF 약자(2글자)
cPais	int	국가 코드. 기본값: `1058`(브라질)
xPais	string	국가명. 기본값: `BRASIL`
fone	string	전화번호
email	string	이메일

det[] — 신고 품목

필드	타입	설명
nItem	int	품목 일련번호
xProd *	string	신고된 재화/상품 설명
NCM *	string	NCM 코드(2 또는 8자리)
qCom *	decimal	수량(> 0)
vUnCom	decimal	단가
vProd *	decimal	품목 총액(> 0)
infAdProd	string	품목 추가 정보

total — 합계

필드	타입	설명
vDC *	decimal	신고 총액(> 0)

transp — 운송

필드	타입	설명
modTrans	int	운송 방식: `0`=우체국, `1`=자가, `2`=운송업체. 기본값: `2`
CNPJTransp	string	운송업체 CNPJ

marketplace — 마켓플레이스 (`tpEmit=1`일 때만)

필드	타입	설명
CNPJ	string	마켓플레이스 CNPJ
xNome	string	마켓플레이스 이름
Site	string	마켓플레이스 사이트

fisco — 세무 기관 (`tpEmit=0`일 때만)

필드	타입	설명
CNPJ	string	기관 CNPJ
xOrgao	string	기관명
UF	string	기관 UF

autXML[] — XML 접근 허가

필드	타입	설명
CNPJ	string	XML 조회/다운로드가 허가된 CNPJ
CPF	string	XML 조회/다운로드가 허가된 CPF

infAdic — 추가 정보

필드	타입	설명
infAdFisco	string	세무 기관 관심 정보
infCpl	string	납세자 관심 보충 정보
infAdMarketPlace	string	마켓플레이스 추가 정보

* 필수 필드. ⚠ 발행자와 수신자에서는 CNPJ 또는 CPF 중 적어도 하나가 필수입니다.

간소화된 예시 (최소 필드)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR"
            }
          },
          "dest": {
            "CPF": "12345678909",
            "xNome": "JOAO DA SILVA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR"
            }
          },
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00
            }
          ],
          "total": {
            "vDC": 150.00
          }
        }

완전한 예시 (모든 필드)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "cUF": 41,
            "serie": 1,
            "nSiteAutoriz": 0
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "SALA 2",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4133334444",
              "email": "contato@exemplo.com"
            }
          },
          "dest": {
            "CNPJ": "98765432000188",
            "xNome": "DESTINATARIO EXEMPLO LTDA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xCpl": "GALPAO 3",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4333335555",
              "email": "destino@exemplo.com"
            }
          },
          "autXML": [
            { "CNPJ": "11222333000144" },
            { "CPF": "98765432100" }
          ],
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00,
              "infAdProd": "Caixa 1 de 2"
            },
            {
              "nItem": 2,
              "xProd": "MATERIAL DE ESCRITORIO",
              "NCM": "48201000",
              "qCom": 10,
              "vUnCom": 8.00,
              "vProd": 80.00,
              "infAdProd": "Caixa 2 de 2"
            }
          ],
          "total": {
            "vDC": 230.00
          },
          "transp": {
            "modTrans": 2,
            "CNPJTransp": "55666777000188"
          },
          "infAdic": {
            "infAdFisco": "Operacao nao sujeita a emissao de nota fiscal",
            "infCpl": "Remessa de bens entre filiais"
          }
        }

성공 응답

        {
          "success": true,
          "message": "DC-e autorizada",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

거부 응답

        {
          "success": false,
          "message": "DC-e rejeitada: Rejeicao: ...",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "225",
            "xMotivo": "Rejeicao: Falha no Schema XML",
            "nProt": "",
            "xml": "",
            "dace": ""
          }
        }

POST /api/dce/consult

DC-e 상태 조회

액세스 키를 사용하여 SEFAZ에서 DC-e의 현재 상태를 조회합니다. DC-e가 취소된 경우, 응답은 취소 데이터를 반영합니다(취소에 대해서는 로컬 데이터베이스가 진실의 원천입니다).

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chDCe *	string	DC-e 액세스 키(44자리)

* 필수 필드.

페이로드 예시

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

응답 — DC-e 활성

        {
          "success": true,
          "message": "Autorizado o uso do DC-e",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Success",
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

응답 — DC-e 취소됨

        {
          "success": true,
          "message": "DC-e Cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Canceled",
            "cStat": "101",
            "xMotivo": "Cancelamento de DCe homologado",
            "nProt": "141250000123457",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml",
            "dhEventoCancel": "2026-06-11T11:00:00-03:00"
          }
        }

POST /api/dce/cancel

DC-e 취소

승인된 DC-e를 취소합니다(이벤트 110111). DC-e가 승인되어 있고(프로토콜 보유) 아직 취소되지 않았어야 합니다. 각 DC-e는 단 한 번만 취소할 수 있습니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chDCe *	string	DC-e 액세스 키(44자리)
xJust *	string	취소 사유(SEFAZ 요건상 최소 15자)
nProt	string	승인 프로토콜. 선택 사항: 생략 시 발행 때 등록된 프로토콜을 사용함

* 필수 필드.

페이로드 예시

        {
          "chDCe": "41250612345678000199990010000000011201234564",
          "xJust": "Cancelamento por erro no preenchimento dos dados da declaracao"
        }

성공 응답

        {
          "success": true,
          "message": "DC-e cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a DC-e",
            "nProtCancel": "141250000123457",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml"
          }
        }

거부된 경우, 응답은 success=false, 거부의 cStat/xMotivo, 그리고 진단을 위해 전송된 XML이 담긴 추가 필드 xmlEnviadoDebug를 반환합니다.

POST /api/dce/pdf

DC-e의 DACE(PDF) 가져오기

DACE — DC-e의 PDF 표현 — 의 URL을 반환합니다. PDF가 아직 저장소에 없으면 요청 시 생성되어 업로드됩니다. 저장소를 사용할 수 없는 경우, PDF는 응답 본문에 base64로 반환됩니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chDCe *	string	DC-e 액세스 키(44자리)

* 필수 필드.

페이로드 예시

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

응답 — PDF URL

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

응답 — base64 폴백 (저장소 사용 불가)

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "pdfBase64": "JVBERi0xLjcKJ...",
            "pdfSize": 84213
          }
        }

GET /api/dce/get_list

DC-e 목록(페이지네이션)

회사의 DC-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링. 값: `"Success"`(승인됨), `"Canceled"`(취소됨), `"Processing"`(처리 중), `"Failed"`(실패), `"Unknown"`(알 수 없음)

* 필수 필드.

호출 예시

GET /api/dce/get_list?page=1&page_size=20&status=Success

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190990010000000011000000013",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping CT-e — 전자 운송장 (Conhecimento de Transporte Eletrônico)

CT-e API(모델 57, 레이아웃 4.00 + NT2025/001)는 전자 운송장의 발행, 취소, 정정(CC-e), 용역 불일치 신고 등록, 조회 및 번호 무효화를 지원합니다. CT-e는 화물 운송 용역의 제공을 문서화합니다. 6가지 운송 방식(도로, 항공, 수운, 철도, 관로, 복합)과 4가지 유형의 CT-e(정상, 보충, 취소, 대체)를 지원합니다. 비즈니스 데이터는 /create 본문에 들어갑니다. 액세스 키의 기술 필드(cCT, cDV, cUF, dhEmi, mod)는 서버에서 자동으로 계산됩니다. serie와 nCT는 선택 사항입니다 — 생략하거나 0으로 보내면 자동으로 할당되고, 요청에 값을 보내면 그대로 적용됩니다(예: SEFAZ 중복 발생 후 번호를 건너뛸 때 유용).

Endpoint	메서드	설명
`/api/cte/create`	POST	CT-e 발행
`/api/cte/cancel`	POST	CT-e 취소 (이벤트 110111)
`/api/cte/cce`	POST	정정서 — CC-e (이벤트 110110)
`/api/cte/desacordo`	POST	용역 불일치 신고 (이벤트 610110, 용역 발주자가 등록)
`/api/cte/consult`	POST	CT-e 상태 조회
`/api/cte/inutilize`	POST	번호 범위 무효화

용역 발주자(운임을 지불하는 자)는 ide.toma에 정의됩니다: 0=발송인, 1=수탁발송인, 2=수령인, 3=수하인, 4=기타(이 경우 ide.toma4를 입력하세요).

POST /api/cte/create

CT-e 발행

전송된 본문으로 CT-e를 발행합니다. 클라이언트는 비즈니스 데이터만 전송합니다. 액세스 키의 기술 식별 필드는 서버에서 계산합니다(ide 테이블 아래 참고 사항 참조). 크레딧 차감은 운영 환경(tpAmb=1)에서 CT-e가 승인될 때만 발생합니다. 아래 예시는 가장 일반적인 경우를 다룹니다: 도로 운송 방식(modal=01) 및 정상 CT-e(tpCTe=0).

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	초 단위 Unix 타임스탬프 (5분 윈도우)

요청의 필수 필드: ide (tpAmb, CFOP, natOp, modal, tpCTe, toma, cMunIni, UFIni, cMunFim, UFFim); CNPJ 또는 CPF 및 xNome을 갖는 emit; CNPJ 또는 CPF를 갖는 rem; CNPJ 또는 CPF를 갖는 dest; vPrest.vTPrest > 0; imp (ICMS 변형 하나 포함). tpCTe=0(정상)인 경우: infCarga(proPred + infQ 최소 1개)와 infModal(ide.modal에 해당하는 운송 방식; modal=01인 경우 rodo.RNTRC가 필수)을 갖는 infCTeNorm. 그 외 모든 필드는 선택 사항입니다.

Body — 최상위 필드

필드	타입	설명
ide *	object	CT-e 식별 정보
emit *	object	발행자(운송인) 데이터
rem *	object	화물 발송인
dest *	object	화물 수하인
vPrest *	object	용역 제공 금액
imp *	object	세금 (ICMS + 조세)
infCTeNorm *	object	정상 CT-e 본문 — `tpCTe=0`(정상) 또는 `3`(대체)일 때 필수
exped	object	수탁발송인 (선택 사항)
receb	object	수령인 (선택 사항)
compl	object	보충 데이터 (비고, 흐름, 배송)
infCteComp	object	보충 대상 CT-e의 키 — `tpCTe=1`(보충)일 때 필수: `{ chCTe }`
infCteAnu	object	취소 대상 CT-e의 키 — `tpCTe=2`(취소)일 때 필수: `{ chCte, dEmi }`
autXML	array	XML 접근이 허가된 CNPJ/CPF: `[{ CNPJ } \| { CPF }]`
infRespTec	object	기술 책임자 — UF별로 서버에서 자동으로 채워짐

ide — 식별 정보

필드	타입	설명
tpAmb *	int	환경: `1`=운영, `2`=테스트
CFOP *	int	거래의 세무 코드(예: 주 내 `5353`, 주 간 `6353`)
natOp *	string	거래 성격(예: `"PRESTACAO DE SERVICO DE TRANSPORTE"`)
modal *	string	운송 방식: `"01"`=도로, `"02"`=항공, `"03"`=수운, `"04"`=철도, `"05"`=관로, `"06"`=복합
tpCTe *	int	CT-e 유형: `0`=정상, `1`=보충, `2`=취소, `3`=대체
tpServ *	int	용역 유형: `0`=정상, `1`=하도급, `2`=재발송, `3`=중간 재발송, `4`=복합 운송 연계 용역
toma *	int	용역 발주자: `0`=발송인, `1`=수탁발송인, `2`=수령인, `3`=수하인, `4`=기타
toma4	object	발주자 데이터 — `toma=4`일 때 필수(아래 테이블 참조)
indIEToma	int	발주자 IE 지표: `1`=ICMS 납세자, `2`=면세, `9`=비납세자(`9`일 때 발주자 IE는 자동으로 생략됨)
cMunIni *	long	용역 시작 자치단체 IBGE 코드(7자리)
xMunIni	string	시작 자치단체명
UFIni *	string	시작 UF(2글자)
cMunFim *	long	용역 종료 자치단체 IBGE 코드(7자리)
xMunFim	string	종료 자치단체명
UFFim *	string	종료 UF(2글자)
cMunEnv	long	발행 자치단체 IBGE 코드
xMunEnv	string	발행 자치단체명
UFEnv	string	발행 UF
retira	int	출발지에서 인수: `0`=예, `1`=아니오. 기본값: `1`
xDetRetira	string	인수 세부 정보
tpImp	int	DACTE 형식: `1`=세로, `2`=가로. 기본값: `1`
infPercurso	array	경로의 UF: `[{ UFPer }]`
dhCont	string	비상 모드 진입 일시(ISO 8601)
xJust	string	비상 사유
serie	int	CT-e 시리즈(액세스 키의 3자리). 선택 사항 — 생략하거나 `0`이면 자동 할당됨(회사의 CT-e 시리즈), 값을 보내면 그대로 적용됨
nCT	long	CT-e 번호(액세스 키를 구성). 선택 사항 — 생략하거나 `0`이면 서버에서 자동 증가됨, 값을 보내면 그대로 적용됨(예: 중복 발생 후 번호를 건너뛸 때 유용)

서버에서 자동으로 채워짐 — 전송할 필요 없음: mod(57로 고정), cCT(8자리 숫자 코드), cDV(검증 자릿수), cUF(발행자 UF에서 도출), dhEmi(현재 일시), tpEmis(기본값 1=정상), procEmi 및 verProc.

toma4 — 발주자 "기타" (`ide.toma=4`일 때)

필드	타입	설명
CNPJ ⚠ / CPF ⚠	string	발주자 서류(둘 중 하나)
IE	string	주 등록번호
xNome	string	법인명/이름
xFant, fone, email	string	상호, 전화번호, 이메일
enderToma	object	주소: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — 발행자(운송인)

필드	타입	설명
CNPJ ⚠	string	발행자 CNPJ(14자리)
CPF ⚠	string	발행자 CPF(11자리)
IE	string	주 등록번호
IEST	string	조세 대납자 주 등록번호
xNome *	string	법인명
xFant	string	상호
CRT	int	조세 체계 코드: `1`=Simples Nacional, `2`=SN 하위한도 초과, `3`=일반 체계, `4`=MEI. 기본값: `3`
enderEmit	object	주소: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — 발송인

필드	타입	설명
CNPJ ⚠ / CPF ⚠	string	발송인 서류(둘 중 하나)
IE	string	주 등록번호(또는 `"ISENTO"`)
xNome	string	법인명/이름
xFant, fone, email	string	상호, 전화번호, 이메일
enderReme	object	발송인 주소(아래 구조 참조)
locColeta	array	수거 장소(선택 사항): `[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — 수하인

필드	타입	설명
CNPJ ⚠ / CPF ⚠	string	수하인 서류(둘 중 하나)
IE	string	주 등록번호(또는 `"ISENTO"`)
xNome	string	법인명/이름
fone, email, ISUF	string	전화번호, 이메일, SUFRAMA 등록번호
enderDest	object	수하인 주소(아래 구조 참조)
locEnt	object	배송 장소(선택 사항): `{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — 수탁발송인 / 수령인 (선택 사항)

필드	타입	설명
CNPJ / CPF	string	서류(둘 중 하나)
IE, xNome, fone, email	string	주 등록번호, 이름, 전화번호, 이메일
enderExped / enderReceb	object	주소(아래의 동일한 일반 구조)

주소 (enderEmit / enderReme / enderExped / enderReceb / enderDest)

필드	타입	설명
xLgr	string	도로명
nro	string	번지
xCpl	string	상세 주소
xBairro	string	구/동
cMun	string	자치단체 IBGE 코드(7자리)
xMun	string	자치단체명
CEP	string	우편번호(8자리) — `enderEmit`에서는 사용되지 않음
UF	string	UF 약자(2글자)
cPais	string	국가 코드(선택 사항, 기본값 1058 브라질)
xPais	string	국가명(선택 사항)
fone	string	전화번호(`enderEmit`에서만)

vPrest — 용역 금액

필드	타입	설명
vTPrest *	decimal	용역 제공 총액(> 0)
vRec	decimal	수취 금액
Comp	array	금액 구성 요소: `[{ xNome, vComp }]` — 예: `"FRETE PESO"`, `"PEDÁGIO"`, `"GRIS"`

imp — 세금

필드	타입	설명
ICMS *	object	ICMS 과세 — 변형 중 하나만 입력(아래 참조)
vTotTrib	decimal	총 조세 추정액
infAdFisco	string	세무 기관 관심 추가 정보
ICMSUFFim	object	DIFAL(주 간 분담, 선택 사항): `{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	연방 조세(선택 사항): `{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — 변형(하나만 입력)

변형	사용 시점	필드
ICMS00	정상 과세	`{ vBC, pICMS, vICMS }` (CST 00)
ICMS20	과세 표준 감액 적용	`{ pRedBC, vBC, pICMS, vICMS }` (CST 20)
ICMS45	면세 / 비과세 / 이연	`{ CST }` — `"40"`=면세, `"41"`=비과세, `"51"`=이연
ICMS60	조세 대납으로 징수된 ICMS	`{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }` (CST 60)
ICMS90	기타(특별 체계)	`{ pRedBC, vBC, pICMS, vICMS, vCred }` (CST 90)
ICMSOutraUF	다른 UF에 납부하는 ICMS	`{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }`
ICMSSN	Simples Nacional 발행자	`{ CST: "90", indSN: 1 }`

infCTeNorm — 정상 CT-e (`tpCTe=0`/`3`일 때 필수)

필드	타입	설명
infCarga *	object	화물 정보(아래 테이블)
infDoc	object	운송 서류(아래 테이블)
infModal *	object	운송 방식 정보(아래 테이블)
docAnt	object	선행 서류(하도급/재발송): `{ emiDocAnt[]{ CNPJ\|CPF, IE, UF, xNome, idDocAnt[] } }`
seg	array	화물 보험: `[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }]` — `respSeg`: 1=발송인…6=발주자
cobr	object	청구/송장: `{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }`
veicNovos	array	운송된 신차: `[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]`
infCteSub	object	대체 — `tpCTe=3`일 때 필수: `{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }`

infCTeNorm.infCarga — 화물

필드	타입	설명
proPred *	string	주요 품목
vCarga	decimal	화물 총액
xOutCat	string	화물의 기타 특성(예: FRIA, GRANEL, REFRIGERADA)
vCargaAverb	decimal	부보 목적의 화물 금액
infQ[] *	array	수량 — 최소 1개: `[{ cUnid, tpMed, qCarga }]`
infQ[].cUnid	string	단위: `"00"`=M³, `"01"`=KG, `"02"`=TON, `"03"`=UNIDADE, `"04"`=LITROS, `"05"`=MMBTU
infQ[].tpMed	string	측정 유형(예: `"PESO BRUTO"`, `"PESO DECLARADO"`)
infQ[].qCarga	decimal	수량

infCTeNorm.infDoc — 운송 서류

필드	타입	설명
infNFe	array	액세스 키별 NF-e: `[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }]` — `chave`는 44자리
infNF	array	종이 송장(레거시): `[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]`
infOutros	array	기타 서류: `[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }]` — `tpDoc`: `"00"`=신고서, `"10"`=관로, `"99"`=기타

infCTeNorm.infModal — 운송 방식(`ide.modal`에 해당하는 것만 입력)

운송 방식	객체	필드
01 도로	rodo	`{ RNTRC* }` — RNTRC 8자리 또는 `"ISENTO"`. 선택 사항: `occ[]` (수거 지시서)
02 항공	aereo	`{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] }` — `dPrevAereo` AAAA-MM-DD
03 수운	aquav	`{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] }` — `direc`: N/L/S/O; `tpNav`: 0=내륙, 1=연안
04 철도	ferrov	`{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] }` — `tpTraf`: 0=자가, 1=상호, 2=도로철도, 3=도로
05 관로	duto	`{ vTar, dIni, dFim }` — 날짜 AAAA-MM-DD
06 복합	multimodal	`{ COTM, indNegociavel, seg[] }` — `indNegociavel`: 0=아니오, 1=예

전체 infModal 블록은 versaoModal(기본값 "4.00")을 받습니다.

compl — 보충 데이터 (선택 사항)

필드	타입	설명
xCaracAd, xCaracSer, xEmi	string	운송 추가 특성 / 용역 추가 특성 / 발행자 이름
origCalc, destCalc	string	운임 계산용 출발 / 도착 자치단체
xObs	string	일반 비고
ObsCont / ObsFisco	array	납세자 / 세무 기관 자유 비고: `[{ xCampo, xTexto }]`
fluxo, Entrega	object	화물 흐름(출발/경유/도착/경로) 및 배송 예정

* 필수 필드. ⚠ 그룹 내에서 CNPJ 또는 CPF 중 적어도 하나가 필수입니다.

간소화된 예시 — 도로 운송 방식, Simples Nacional

        {
          "ide": {
            "CFOP": 5353,
            "natOp": "PRESTACAO DE SERVICO DE TRANSPORTE",
            "tpAmb": 2,
            "tpCTe": 0,
            "modal": "01",
            "tpServ": 0,
            "cMunEnv": 3550308,
            "xMunEnv": "SAO PAULO",
            "UFEnv": "SP",
            "cMunIni": 3550308,
            "xMunIni": "SAO PAULO",
            "UFIni": "SP",
            "cMunFim": 3304557,
            "xMunFim": "RIO DE JANEIRO",
            "UFFim": "RJ",
            "retira": 1,
            "indIEToma": 9,
            "toma": 0
          },
          "emit": {
            "CNPJ": "26638419000167",
            "IE": "141507411110",
            "CRT": 1,
            "xNome": "TF COMERCIO DE PRESENTES LTDA",
            "enderEmit": {
              "xLgr": "RUA QUINTANA",
              "nro": "34",
              "xBairro": "CIDADE MONCOES",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "04571010",
              "UF": "SP",
              "fone": "1133334444"
            }
          },
          "rem": {
            "CNPJ": "11111111000111",
            "IE": "ISENTO",
            "xNome": "EMPRESA REMETENTE LTDA",
            "fone": "1122223333",
            "enderReme": {
              "xLgr": "AV PAULISTA",
              "nro": "1500",
              "xBairro": "BELA VISTA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01310200",
              "UF": "SP"
            }
          },
          "dest": {
            "CNPJ": "22222222000122",
            "IE": "ISENTO",
            "xNome": "EMPRESA DESTINATARIA LTDA",
            "fone": "2133334444",
            "enderDest": {
              "xLgr": "AV RIO BRANCO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3304557",
              "xMun": "RIO DE JANEIRO",
              "CEP": "20040002",
              "UF": "RJ"
            }
          },
          "vPrest": {
            "vTPrest": 1500.00,
            "vRec": 1500.00,
            "Comp": [
              { "xNome": "FRETE PESO", "vComp": 1500.00 }
            ]
          },
          "imp": {
            "ICMS": {
              "ICMSSN": { "CST": "90", "indSN": 1 }
            },
            "vTotTrib": 0
          },
          "infCTeNorm": {
            "infCarga": {
              "vCarga": 10000.00,
              "proPred": "PRODUTOS DIVERSOS",
              "infQ": [
                { "cUnid": "01", "tpMed": "PESO BRUTO", "qCarga": 1000.0000 }
              ]
            },
            "infDoc": {
              "infNFe": [
                { "chave": "35260526638419000167550030000006561341688760" }
              ]
            },
            "infModal": {
              "versaoModal": "4.00",
              "rodo": {
                "RNTRC": "12345678"
              }
            }
          }
        }

성공 응답

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

거부 응답

        {
          "success": false,
          "message": "Rejeicao: ...",
          "data": {
            "cStat": "539",
            "chCTe": "",
            "nProt": "",
            "xml": ""
          }
        }

POST /api/cte/cancel

CT-e 취소

승인된 CT-e를 취소합니다(이벤트 110111). CT-e가 승인되어 있고(프로토콜 보유) 아직 취소되지 않았어야 합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chCTe *	string	CT-e 액세스 키(44자리)
xJust *	string	취소 사유(SEFAZ 요건상 최소 15자)
nProt	string	승인 프로토콜. 선택 사항: 생략 시 발행 때 등록된 프로토콜을 사용함

* 필수 필드.

페이로드 예시

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xJust": "Cancelamento por erro no preenchimento dos dados da prestacao"
        }

성공 응답

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123457",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/cce

정정서 (CC-e)

승인된 CT-e에 대해 전자 정정서(이벤트 110110)를 등록합니다. CC-e는 세금에 영향을 주는 값, 발행자/발주자/발송인/수하인을 변경하는 등록 정보, 또는 발행일을 정정할 수 없습니다. 각 정정은 그룹, 필드 및 새 값을 지정합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chCTe *	string	CT-e 액세스 키(44자리)
infCorrecao[] *	array	정정(최소 1개, 최대 20개)
infCorrecao[].grupoAlterado *	string	변경된 그룹(예: `"ide"`, `"rem"`, `"dest"`)
infCorrecao[].campoAlterado *	string	변경된 필드(예: `"xNome"`)
infCorrecao[].valorAlterado *	string	새 값
infCorrecao[].nroItemAlterado	int	변경된 항목 번호(그룹이 목록일 때)

* 필수 필드. 사용 조건(xCondUso)은 서버에서 자동으로 채워집니다.

페이로드 예시

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "infCorrecao": [
            {
              "grupoAlterado": "compl",
              "campoAlterado": "xObs",
              "valorAlterado": "OBSERVACAO CORRIGIDA"
            }
          ]
        }

성공 응답

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123458",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/desacordo

용역 불일치 신고

용역 불일치 신고(이벤트 610110)를 등록합니다 — 용역 발주자가 CT-e에 기재된 용역이 계약된 내용과 일치하지 않음을 표명하는 데 사용됩니다. 이벤트를 등록하는 CNPJ(발주자)는 토큰 회사의 것입니다. CT-e의 발행자일 필요는 없습니다.

필수 헤더

헤더	타입	설명
token	string	회사(발주자)의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chCTe *	string	CT-e 액세스 키(44자리)
xObs *	string	불일치 설명(최소 15자)

* 필수 필드. 불일치 거래 지표는 항상 1입니다(PL-CTe v4.00).

페이로드 예시

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xObs": "Valor do frete cobrado diverge do contratado entre as partes"
        }

성공 응답

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123459"
          }
        }

POST /api/cte/consult

CT-e 상태 조회

액세스 키를 사용하여 SEFAZ에서 CT-e의 상태를 조회합니다. CT-e가 취소된 경우(로컬 등록), 응답은 취소를 반영합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chCTe *	string	CT-e 액세스 키(44자리)

* 필수 필드.

페이로드 예시

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

응답

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

POST /api/cte/inutilize

번호 범위 무효화

사용되지 않을 CT-e 번호 범위를 무효화합니다(예: 일련번호 단절 후). 무효화는 확정적입니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사의 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
tpAmb *	int	환경: `1`=운영, `2`=테스트
CNPJ *	string	발행자 CNPJ(14자리)
ano *	int	번호 연도(2자리, 예: 2026의 경우 `26`)
serie *	int	번호 시리즈
nCTIni *	long	범위 시작 번호
nCTFin *	long	범위 종료 번호(≥ `nCTIni`)
xJust *	string	사유(최소 15자)
mod	int	모델. 기본값: `57`

* 필수 필드.

페이로드 예시

        {
          "tpAmb": 2,
          "CNPJ": "26638419000167",
          "ano": 26,
          "serie": 1,
          "nCTIni": 51,
          "nCTFin": 55,
          "xJust": "Quebra de sequencia na numeracao por falha no sistema emissor"
        }

성공 응답

        {
          "success": true,
          "message": "Inutilizacao de numero homologado",
          "data": {
            "cStat": "102",
            "chCTe": "",
            "nProt": "135260000123460"
          }
        }

GET /api/cte/get_list

CT-e 목록(페이지네이션)

회사의 CT-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링. 값: `"Success"`(승인됨), `"Canceled"`(취소됨), `"Processing"`(처리 중), `"Failed"`(실패), `"Unknown"`(알 수 없음)

* 필수 필드.

호출 예시

GET /api/cte/get_list?page=1&page_size=20&status=Success

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190570010000000011000000019",
                "serie": 1,
                "number": 1,
                "modal": "01",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

vpn_key SSO — 토큰을 통한 자동 로그인

기본 URL (프로덕션)

https://api.tffiscal.com

인증

Headers: sign, timestamp, token

티켓 유효기간

60초 — 일회용

SSO(싱글 사인온)를 사용하면 ERP가 사용자를 위해 TFiscal로의 직접 액세스 링크를 생성할 수 있으며, 자격 증명을 입력하지 않고도 해당 회사에 원하는 언어로 이미 인증된 상태로 접속할 수 있습니다.

작동 방식:

ERP는 회사 토큰을 보내 POST /api/sso/create_ticket을 호출합니다.
TFiscal은 일회용 불투명 티켓을 포함한 redirectUrl을 반환합니다.
ERP는 사용자의 브라우저를 해당 URL로 리디렉션합니다.
페이지가 티켓을 소비하고 사용자는 회사 패널에 자동으로 로그인됩니다.

⚠️ 보안: 실제 회사 토큰은 URL에 절대 표시되지 않습니다. 단기 티켓(60초 유효, 일회용)만 브라우저에 노출됩니다.

POST /api/sso/create_ticket

자동 로그인 링크 생성

60초 이내에 사용할 수 있는 일회용 티켓을 생성하여 사용자를 토큰에 해당하는 회사 패널에 자동으로 로그인시킵니다.

필수 헤더

Header	타입	설명
token	string	회사 토큰 (NF-e 발행에 사용되는 것과 동일)
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 초 타임스탬프 (5분 창)

Payload

        {
          "token": "TOKEN_DA_EMPRESA",
          "language": "br",
          "page": "emitir_nfe"
        }

필드

필드	필수	타입	설명
token	예	string	회사 토큰 (`w_company.token`) — `/api/invoice/create`에서 사용하는 것과 동일
language	아니오	string	UI 언어: `br`, `en`, `zh`, `es`, `ja`, `ko`. 기본값: `br`
page	아니오	string	로그인 후 랜딩 페이지. 허용된 값: `emitir_nfe`. 비어 있거나 누락된 경우 기본 패널(`/company/kanban`)이 열립니다.

성공 응답

        {
          "success": true,
          "message": "ticket",
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "expiresInSeconds": 60,
          "expiresAt": "2026-04-24T18:34:56.0000000Z"
        }

응답 필드

필드	타입	설명
success	boolean	티켓이 성공적으로 생성된 경우 `true`
ticket	string	불투명 티켓 (무작위, 32바이트 base64url)
redirectUrl	string	ERP가 사용자의 브라우저를 리디렉션해야 할 전체 URL
expiresInSeconds	number	유효 기간(초) (항상 60)
expiresAt	string	UTC 만료 날짜/시간 (ISO 8601)

오류 응답

메시지	원인
`Token은 필수입니다`	body에 `token` 필드가 전송되지 않음
`유효하지 않은 Token`	토큰이 등록된 회사와 일치하지 않음
`이 토큰은 여러 회사와 연결되어 있습니다. 액세스하려는 회사의 특정 토큰을 보내주세요.`	여러 회사가 있는 통합업체 토큰 — 특정 회사의 토큰을 보내주세요
`Rate limit exceeded`	동일한 토큰에 대해 분당 30회 이상 호출

POST /api/sso/consume_ticket

티켓 소비로 세션 JWT 받기

/api/sso/create_ticket로 생성된 티켓을 TFiscal 세션 JWT로 교환합니다. 이 엔드포인트는 프론트엔드(/sso 경로)에서 호출되며 sign/timestamp 헤더가 필요하지 않습니다 — 불투명 티켓 자체가 자격 증명입니다. 각 티켓은 한 번만 소비할 수 있으며 60초 후에 만료됩니다.

Body

필드	유형	설명
ticket *	string	`create_ticket`가 반환한 티켓

* 필수 필드.

페이로드 예시

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

성공 응답

        {
          "success": true,
          "message": "Login succeeded",
          "access_token": "eyJhbGciOi...",
          "type": "user",
          "uid": 1234,
          "company_id": 5678,
          "language": "br",
          "page": "emitir_nfe"
        }

응답 필드

필드	유형	설명
access_token	string	세션 JWT (유효기간 365일). TFiscal 호출의 `Authorization` 헤더에서 사용
type	string	사용자 유형 (`user`, `admin` 등)
uid	int	내부 사용자 ID
company_id	int	`create_ticket`에서 선택한 회사 ID
language	string	`create_ticket`에서 선택한 언어 (항상 정규화)
page	string	대상 페이지 (설정되지 않으면 빈 문자열)

오류 응답

메시지	원인
`Ticket inválido`	Body에 `ticket` 필드 없음
`Ticket inválido ou expirado`	티켓이 존재하지 않거나 이미 소비됨, 또는 60초 만료
`Rate limit exceeded`	동일 IP에서 분당 60회 초과
`Sessão inválida`	티켓에 연결된 사용자가 더 이상 존재하지 않음

lock 제한 및 보안

티켓 특성

특성	값
유효 기간	생성 후 60초
사용	일회용 — 소비 후 재사용 불가
속도 제한	토큰당 분당 30개 티켓 · IP당 분당 60회 소비
저장소	자동 TTL이 있는 MongoDB — 만료된 티켓은 삭제됩니다

탐색 제한

SSO를 통해 인증된 사용자는 해당 회사 화면(/invoice/company/*)에 만 액세스할 수 있습니다. 다른 영역(배급업체 패널, 일반 보고서, 관리)에 액세스하려는 시도는 회사 패널로 자동 리디렉션됩니다.

로그인 후 세션

티켓을 JWT와 교환한 후 사용자는 TFiscal의 정상 세션을 가집니다(JWT는 365일 유효, 기존 로그인과 동일). 60초는 티켓 생성과 링크 열기 사이의 창일 뿐입니다 — 그 후 사용자는 로그아웃할 때까지 정상적으로 로그인된 상태를 유지합니다.

⚠️ 중요: create_ticket은 ERP에 의해 서버 측에서만 호출되어야 합니다. 브라우저에서 이 엔드포인트를 직접 호출하지 마세요 — 프론트엔드에서 회사 토큰이 노출됩니다.

badge 회계사(Contador)

회사에 연결된 회계사 등록 데이터를 조회하기 위한 API. 특정 회사를 담당하는 회계사의 전체 데이터를 가져와야 하는 외부 회계 시스템에 유용합니다.

POST /api/accountant/get_info

회사에 연결된 회계사 정보 조회

지정된 회사에 연결된 회계사의 전체 등록 데이터를 반환합니다. 회계사는 사전에 회사(동일 CNPJ)에 연결되어 있어야 하고, 제공된 이메일은 등록과 일치해야 합니다.

필수 헤더

헤더	유형	설명
token	string	회사 토큰 또는 인티그레이터 B2B 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
companyId *	int	토큰에 연결된 회사 ID
accountantId *	string	회계사 ObjectId (24자 16진수)
email *	string	회계사 이메일 (등록과 일치해야 함)

* 필수 필드.

페이로드 예시

        {
          "companyId": 12345,
          "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
          "email": "contador@escritorio.com"
        }

성공 응답

        {
          "success": true,
          "data": {
            "email": "contador@escritorio.com",
            "officeDocumentType": "CNPJ",
            "officeDocument": "12345678000199",
            "officeName": "Escritório Contábil LTDA",
            "responsibleName": "João da Silva",
            "crc": "SP123456/O-7",
            "accountantCpf": "12345678909",
            "workAddress": "Rua Exemplo, 100 - Centro - São Paulo/SP",
            "site": "https://escritorio.com",
            "landline": "1133334444",
            "mobile": "11999998888",
            "assistantName": "Maria Souza",
            "assistantEmail": "maria@escritorio.com",
            "assistantPhone": "11988887777",
            "observations": "Atendimento de segunda a sexta, 9h às 18h"
          }
        }

응답 필드

필드	유형	설명
email	string	회계사 기본 이메일
officeDocumentType	string	사무소 문서 유형: "CNPJ" 또는 "CPF"
officeDocument	string	사무소 문서 (숫자만)
officeName	string	사무소 법인명 / 명칭
responsibleName	string	담당 회계사 이름
crc	string	CRC 번호 (브라질 지역 회계 위원회)
accountantCpf	string	회계사 CPF (숫자만)
workAddress	string	사업장 주소
site	string	사무소 웹사이트
landline	string	유선 전화
mobile	string	휴대전화
assistantName	string	비서 이름
assistantEmail	string	비서 이메일
assistantPhone	string	비서 전화
observations	string	등록 자유 메모

오류 응답

메시지	원인
会计师ID参数异常或不存在	`accountantId` 누락 또는 유효하지 않은 ObjectId
该会计师邮箱异常或不存在	`email` 무효 또는 미등록
发票账号{companyId}异常或不存在	`companyId`가 토큰 사용자에 속하지 않음
该会计师未绑定该发票账号	회계사가 지정된 회사에 연결되지 않음

verified_user CPF 및 CNPJ 검증

브라질 연방국세청 (Receita Federal)의 공식 데이터베이스로 CPF와 CNPJ를 검증하는 API입니다. CPF는 이름, 등록 상태, 나이 및 미성년자 자동 차단 (LGPD 준수)을 반환합니다. CNPJ는 상호, 상호명, 주소, 주주 정보 및 전체 등록 상태를 반환합니다. 세금 문서 발행 전 등록 정보 확인, 비정상 상태 (정지, 취소, 폐업)의 납세자 식별에 권장됩니다.

POST /api/invoice/validar_cpf_cnpj

CPF (생년월일 포함) 또는 CNPJ를 브라질 연방국세청 공식 데이터베이스로 검증

CPF 또는 CNPJ를 포맷팅 유무에 관계없이 받습니다. 문서 유형은 자동으로 감지됩니다. CPF의 경우 dataNascimento는 필수입니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰 또는 B2B 통합자 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초, 5분 유효 기간)

Body

필드	타입	설명
cpfCnpj *	string	CPF (11자리 숫자) 또는 CNPJ (14자). 포맷팅 허용.
dataNascimento	string	생년월일 — CPF의 경우에만 필수. 허용 형식: `dd/MM/yyyy`, `dd-MM-yyyy` 또는 `ddMMyyyy`.

* 필수 필드.

페이로드 예시 — CPF

        {
          "cpfCnpj": "407.105.368-28",
          "dataNascimento": "09/01/1997"
        }

페이로드 예시 — CNPJ

        {
          "cpfCnpj": "03.354.151/0001-36"
        }

응답 — CPF 발견, 정상 상태

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "nome": "FULANO DE TAL",
            "situacao_codigo": "0",
            "situação_descricao": "REGULAR",
            "menor_de_idade_lgpd": false,
            "idade": 29,
            "data_nascimento": "1997-01-09"
          }
        }

응답 — 미성년자 CPF (LGPD)

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "situação_descricao": "Menor de idade",
            "menor_de_idade_lgpd": true
          }
        }

응답 — CPF를 찾을 수 없음

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "Situação": "CPF não encontrado"
          }
        }

응답 — 생년월일이 CPF와 일치하지 않음

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "Situação": "Data de nascimento não confere com o CPF"
          }
        }

응답 — CNPJ 발견

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "03354151000136",
            "nome": "EMPRESA EXEMPLO LTDA",
            "situacao_codigo": "2",
            "situação_descricao": "Ativo",
            "nome_empresarial": "EMPRESA EXEMPLO LTDA",
            "nome_fantasia": "EXEMPLO",
            "data_situacao": "20180515",
            "motivo_situacao": ""
          }
        }

응답 — CNPJ를 찾을 수 없음

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "12345678000199",
            "Situação": "Não encontrado"
          }
        }

CPF 상태 코드

코드	설명
0	정상 (REGULAR)
2	정지
3	명의자 사망
4	정규화 보류
5	중복으로 인한 취소
8	무효
9	직권 취소

CNPJ 상태 코드

코드	설명
1	무효
2	활성
3	정지
4	부적격
8	폐업

오류 응답

메시지	원인
cpfCnpj é obrigatório	`cpfCnpj` 필드 누락 또는 비어있음
CPF inválido, verifique a quantidade de dígitos	제출된 CPF가 11자리가 아닙니다
CPF inválido	제출된 CPF의 검증 자릿수가 잘못되었거나 영문자를 포함합니다
CNPJ inválido, verifique a quantidade de dígitos	제출된 CNPJ가 14자가 아닙니다
CNPJ inválido	제출된 CNPJ의 검증 자릿수가 잘못되었습니다
é necessário informar a data de nascimento	CPF가 `dataNascimento` 없이 전송됨
dataNascimento inválida (use dd/MM/yyyy)	날짜 형식이 허용된 패턴과 일치하지 않음

NFE API 문서

중요한 API 필드

송장 발행 프로세스 흐름

1. 기업 등록

2. 정보 전송

3. 송장 발행

4. 결과 반환

5. 파일 생성

세무 검증

Success

Failure

엔드포인트 빠른 참조

성공

클라이언트 오류

서버 오류

NFE API

sync_alt System Flow

input Input Data

settings Processing

download Output

주요 엔드포인트

필수 헤더

Body

페이로드 예시

응답

필수 헤더

Body

페이로드 예시

응답

필수 헤더

Body

페이로드 예시

예시 — 회사에 NFC-e와 CT-e 활성화

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

호출 예시

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

호출 예시

응답

응답 예시

필수 헤더

Body — 최상위 필드

Body — cliente (객체, 필수)

Body — products[] (배열, 최소 1개 항목)

Body — products[].impostos / products[].tax_info

Body — products[].ii (수입세)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (객체, 선택)

Body — transportation (객체, 선택)

Body — pag_info[] (배열, 선택)

간소화된 예시

완전한 예시 (모든 필드)

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

Body

페이로드 예시

필수 헤더

Body

페이로드 예시

필수 헤더

Body

페이로드 예시

필수 헤더

Body

Body — `cliente` (객체, 필수)

Body — `products[]` (배열, 최소 1개 항목)

Body — `products[].impostos` / `products[].tax_info`

Body — `products[].ii` (수입세)

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address` (객체, 선택)

Body — `transportation` (객체, 선택)

Body — `pag_info[]` (배열, 선택)

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` 및 `cofins[]`(동일 구조)

Body — `ibs_cbs[]`(세제 개혁)

Body — `is[]`(선택세)